@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/lifecycle/install-signal-handlers.js

@@ -1,112 +0,0 @@
-// Wires SIGTERM / SIGINT to the ShutdownCoordinator.
-//
-// Lives in its own file (separate from index.ts) so the compiled dist/index.js
-// — which reads env vars for the ingest-token / user-id — does not also contain
-// the network-send call site.  OpenClaw's plugin-install heuristic flags the
-// combination as possible credential harvesting (false positive, but worth
-// avoiding by keeping each compiled file single-purpose).
-//
-// All env-var-bearing context is passed in by the caller via the typed
-// argument shape, NOT read from process.env here.
-import { LiveAdapter } from '../live/live-adapter.js';
-import { logger, formatError } from '../logger.js';
-import { initiateShutdown } from './shutdown-coordinator.js';
-const TAG = 'shutdown';
-/** The phase-2 drain body. Exported for direct unit-testing of the teardown
- *  ordering + the StateManager flush wiring (the signal handler itself can't
- *  be tested without process.exit). Every step is individually guarded so one
- *  failing teardown never aborts the rest. */
-export async function performShutdownDrain(deps) {
-    // Stop the approval-mode listener BEFORE the adapter shuts down.
-    // The listener's tick may call createOrderTool which needs the
-    // adapter; once stop() resolves, no new tick will fire.
-    if (deps.proposalListener) {
-        try {
-            await deps.proposalListener.stop();
-        }
-        catch (err) {
-            logger.warn(TAG, `proposalListener stop failed: ${formatError(err)}`);
-        }
-    }
-    // Flush any pending audit-trail POSTs.
-    if (deps.tradeStore) {
-        try {
-            await deps.tradeStore.drain();
-        }
-        catch (err) {
-            logger.warn(TAG, `tradeStore drain failed: ${formatError(err)}`);
-        }
-    }
-    // Stop background loops + close WS + DELETE listenKey.
-    const live = deps.runtime.adapter;
-    if (live instanceof LiveAdapter) {
-        try {
-            live.shutdown();
-        }
-        catch (err) {
-            logger.warn(TAG, `LiveAdapter.shutdown failed: ${formatError(err)}`);
-        }
-    }
-    // Stop the watcher last so it doesn't fire a stop after the
-    // adapter is gone.
-    const watcher = deps.runtime.stopWatcher;
-    if (watcher) {
-        try {
-            watcher.stop();
-        }
-        catch (err) {
-            logger.warn(TAG, `stopWatcher.stop failed: ${formatError(err)}`);
-        }
-    }
-    // Stop the paper market feed so its interval doesn't outlive the process.
-    const marketFeed = deps.runtime.marketFeed;
-    if (marketFeed) {
-        try {
-            marketFeed.stop();
-        }
-        catch (err) {
-            logger.warn(TAG, `marketFeed.stop failed: ${formatError(err)}`);
-        }
-    }
-    // Flush the paper StateManager AFTER all mutation sources are stopped, so
-    // the 1s debounce window doesn't drop the final fills/closes/PnL on restart.
-    // flush() clears the timer and awaits the atomic save; completes in ms
-    // inside the drain budget. Without this, every restart silently lost up to
-    // ~1s of paper state (a just-closed position would resurrect on boot).
-    if (deps.stateManager) {
-        try {
-            await deps.stateManager.flush();
-        }
-        catch (err) {
-            logger.warn(TAG, `stateManager flush failed: ${formatError(err)}`);
-        }
-    }
-}
-/** Register graceful-shutdown handlers.  Idempotent — repeat signals during
- *  the drain are logged + ignored.  After the coordinator resolves we call
- *  process.exit(0) so systemd doesn't escalate to SIGKILL. */
-export function installSignalHandlers(deps) {
-    let invoked = false;
-    const onSignal = (signal) => {
-        if (invoked) {
-            logger.info(TAG, `Received ${signal} during shutdown — ignoring`);
-            return;
-        }
-        invoked = true;
-        logger.info(TAG, `Received ${signal} — initiating graceful shutdown`);
-        void initiateShutdown({
-            reason: signal,
-            callbacks: {
-                onDrainComplete: () => performShutdownDrain(deps),
-            },
-        }).then(() => {
-            logger.info(TAG, 'Shutdown drain complete — exit(0)');
-            process.exit(0);
-        }).catch((err) => {
-            logger.error(TAG, `Shutdown threw: ${formatError(err)} — exit(1)`);
-            process.exit(1);
-        });
-    };
-    process.on('SIGTERM', onSignal);
-    process.on('SIGINT', onSignal);
-}

package/assets/plugin/lifecycle/shutdown-coordinator.d.ts

@@ -1,43 +0,0 @@
-export declare class ShutdownInProgressError extends Error {
-    constructor(opName: string);
-}
-interface InFlightOp {
-    name: string;
-    startedAt: number;
-}
-/** True once SIGTERM/SIGINT has been received. New risky ops should be refused. */
-export declare function isShuttingDown(): boolean;
-/** Throw ShutdownInProgressError if shutdown has begun. Use as a guard at the
- *  top of risky entry points (new bracket attach, modify_stop, new order). */
-export declare function assertNotShuttingDown(opName: string): void;
-/** Register an in-flight operation. The returned function MUST be called when
- *  the op ends. Prefer `trackOp` for typical async cases. */
-export declare function registerOp(name: string): () => void;
-/** Convenience: register + auto-deregister around a promise. */
-export declare function trackOp<T>(name: string, fn: () => Promise<T>): Promise<T>;
-/** Snapshot of currently in-flight ops. Mainly for diagnostics + tests. */
-export declare function getInFlight(): InFlightOp[];
-export interface ShutdownCallbacks {
-    /** Run after in-flight ops drain (or phase-1 deadline hits). Last chance to
-     *  flush the trade ingest queue and tear down adapters. Errors are logged
-     *  + swallowed. */
-    onDrainComplete?: () => Promise<void>;
-}
-export interface ShutdownOptions {
-    reason: string;
-    /** Phase 1 budget — wait for tracked ops to settle. Default 3000 ms. */
-    inFlightDeadlineMs?: number;
-    /** Phase 2 budget — onDrainComplete callback. Default 2000 ms. */
-    drainCallbackDeadlineMs?: number;
-    /** Hard wall-clock deadline across both phases. Default 5000 ms. */
-    totalDeadlineMs?: number;
-    callbacks?: ShutdownCallbacks;
-}
-/** Run the drain sequence. Idempotent — second call returns the first call's
- *  promise. Resolves when both phases are complete or the wall-clock deadline
- *  is hit (whichever is first). The signal handler should `process.exit` after
- *  this resolves. */
-export declare function initiateShutdown(opts: ShutdownOptions): Promise<void>;
-/** Test seam — reset module-level state. Do NOT call from production. */
-export declare function __resetForTesting(): void;
-export {};

package/assets/plugin/lifecycle/shutdown-coordinator.js

@@ -1,131 +0,0 @@
-// Process-wide graceful shutdown coordinator.
-//
-// Two responsibilities:
-//   1. Track in-flight risky operations (bracket attach/modify, new entries)
-//      so a SIGTERM-driven shutdown can wait for them before exiting.
-//   2. Block NEW risky operations from starting once shutdown begins, while
-//      still allowing risk-reducing ops (closePosition, reduceOnly) through.
-//
-// Why a global module instead of a constructor-injected service:
-//   - Many files own the at-risk operations (BracketManager, LiveAdapter).
-//     Threading a coordinator through every constructor is mechanical noise
-//     and the caller graph is fixed for this process's lifetime.
-//   - Process-wide state is a fine match for a singleton — one shutdown event
-//     per process, ever.
-//   - Tests reset the singleton via `__resetForTesting()`.
-import { logger } from '../logger.js';
-const TAG = 'shutdown-coordinator';
-export class ShutdownInProgressError extends Error {
-    constructor(opName) {
-        super(`shutting_down: refused to start ${opName}`);
-        this.name = 'ShutdownInProgressError';
-    }
-}
-let _shuttingDown = false;
-const _inFlight = new Map();
-/** True once SIGTERM/SIGINT has been received. New risky ops should be refused. */
-export function isShuttingDown() {
-    return _shuttingDown;
-}
-/** Throw ShutdownInProgressError if shutdown has begun. Use as a guard at the
- *  top of risky entry points (new bracket attach, modify_stop, new order). */
-export function assertNotShuttingDown(opName) {
-    if (_shuttingDown) {
-        throw new ShutdownInProgressError(opName);
-    }
-}
-/** Register an in-flight operation. The returned function MUST be called when
- *  the op ends. Prefer `trackOp` for typical async cases. */
-export function registerOp(name) {
-    const handle = Symbol(name);
-    _inFlight.set(handle, { name, startedAt: Date.now() });
-    return () => { _inFlight.delete(handle); };
-}
-/** Convenience: register + auto-deregister around a promise. */
-export async function trackOp(name, fn) {
-    const done = registerOp(name);
-    try {
-        return await fn();
-    }
-    finally {
-        done();
-    }
-}
-/** Snapshot of currently in-flight ops. Mainly for diagnostics + tests. */
-export function getInFlight() {
-    return Array.from(_inFlight.values()).map(o => ({ ...o }));
-}
-/** Run the drain sequence. Idempotent — second call returns the first call's
- *  promise. Resolves when both phases are complete or the wall-clock deadline
- *  is hit (whichever is first). The signal handler should `process.exit` after
- *  this resolves. */
-export function initiateShutdown(opts) {
-    if (_shuttingDownPromise)
-        return _shuttingDownPromise;
-    _shuttingDown = true;
-    _shuttingDownPromise = runShutdown(opts);
-    return _shuttingDownPromise;
-}
-let _shuttingDownPromise = null;
-async function runShutdown(opts) {
-    // Phase-1 default sized for the worst-case bracket retry loop:
-    //   3 attempts × ~500ms API + 1s + 2s backoff = ~4.5s.  6s leaves margin.
-    // Phase-2 default covers TradeStoreClient.drain (network-bounded) + listen
-    // key teardown (one DELETE).
-    // Total wall-clock 10s sits well inside systemd's default TimeoutStopSec.
-    const inFlightDeadline = opts.inFlightDeadlineMs ?? 6_000;
-    const callbackDeadline = opts.drainCallbackDeadlineMs ?? 3_000;
-    const totalDeadline = opts.totalDeadlineMs ?? 10_000;
-    const t0 = Date.now();
-    const remaining = () => Math.max(0, totalDeadline - (Date.now() - t0));
-    const opsAtStart = Array.from(_inFlight.values()).map(o => o.name);
-    logger.info(TAG, `Shutdown initiated (reason=${opts.reason}). In-flight ops: ${opsAtStart.length}` +
-        (opsAtStart.length ? ` [${opsAtStart.join(', ')}]` : ''));
-    // Phase 1: wait for in-flight ops to drain.
-    const phase1Budget = Math.min(inFlightDeadline, remaining());
-    await waitForInFlightDrain(phase1Budget);
-    if (_inFlight.size > 0) {
-        const stuckOps = Array.from(_inFlight.values()).map(o => o.name);
-        logger.warn(TAG, `Phase 1 timed out after ${phase1Budget}ms — ${_inFlight.size} op(s) still in flight: [${stuckOps.join(', ')}]`);
-    }
-    else if (opsAtStart.length > 0) {
-        logger.info(TAG, `Phase 1 complete: in-flight ops drained in ${Date.now() - t0}ms`);
-    }
-    // Phase 2: callback drain (trade-store + adapter).
-    if (opts.callbacks?.onDrainComplete) {
-        const phase2Budget = Math.min(callbackDeadline, remaining());
-        if (phase2Budget <= 0) {
-            logger.warn(TAG, 'Phase 2 skipped — total deadline exhausted by phase 1');
-        }
-        else {
-            try {
-                await Promise.race([
-                    opts.callbacks.onDrainComplete(),
-                    new Promise(resolve => setTimeout(resolve, phase2Budget)),
-                ]);
-                logger.info(TAG, `Phase 2 complete (total elapsed ${Date.now() - t0}ms)`);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                logger.warn(TAG, `Phase 2 callback threw: ${msg}`);
-            }
-        }
-    }
-    logger.info(TAG, `Shutdown coordinator finished in ${Date.now() - t0}ms`);
-}
-async function waitForInFlightDrain(budgetMs) {
-    if (_inFlight.size === 0)
-        return;
-    const start = Date.now();
-    // Poll-based; in-flight ops settle through their own promise chains and
-    // unregister themselves. Cheaper than wiring an emitter just for this.
-    while (_inFlight.size > 0 && Date.now() - start < budgetMs) {
-        await new Promise(r => setTimeout(r, 50));
-    }
-}
-/** Test seam — reset module-level state. Do NOT call from production. */
-export function __resetForTesting() {
-    _shuttingDown = false;
-    _shuttingDownPromise = null;
-    _inFlight.clear();
-}

package/assets/plugin/lifecycle/trading-operation-lock.d.ts

@@ -1,17 +0,0 @@
-/**
- * Narrow process-local serialization boundary shared by guarded trading
- * operations. Account and per-symbol operations intentionally use one queue:
- * a Wave 9 portfolio transition must be atomic with respect to the legacy
- * stop watcher, while callers gain no adapter/execution capability from the
- * lock itself.
- */
-export interface TradingOperationLock {
-    withAccountLock<T>(operation: string, run: () => Promise<T>): Promise<T>;
-    withSymbolLock<T>(symbol: string, operation: string, run: () => Promise<T>): Promise<T>;
-}
-export declare class SerialTradingOperationLock implements TradingOperationLock {
-    private tail;
-    private enqueue;
-    withAccountLock<T>(_operation: string, run: () => Promise<T>): Promise<T>;
-    withSymbolLock<T>(_symbol: string, _operation: string, run: () => Promise<T>): Promise<T>;
-}

package/assets/plugin/lifecycle/trading-operation-lock.js

@@ -1,14 +0,0 @@
-export class SerialTradingOperationLock {
-    tail = Promise.resolve();
-    enqueue(run) {
-        const result = this.tail.then(run, run);
-        this.tail = result.then(() => undefined, () => undefined);
-        return result;
-    }
-    withAccountLock(_operation, run) {
-        return this.enqueue(run);
-    }
-    withSymbolLock(_symbol, _operation, run) {
-        return this.enqueue(run);
-    }
-}

package/assets/plugin/live/bracket-id.d.ts

@@ -1,26 +0,0 @@
-import type { BracketId, BracketRole } from './bracket-types.js';
-import type { VenueId } from '../venues/symbols.js';
-/** Generate a fresh 16-char hex bracketId. */
-export declare function generateBracketId(): BracketId;
-/** Build a clientOrderId for a given bracket + role. Emits the CURRENT
- *  (`bkt…`) scheme only — never the legacy `rc-` scheme. */
-export declare function buildBracketCid(bracketId: BracketId, role: BracketRole): string;
-/** Parse a clientOrderId. Recognises BOTH the current `bkt…` scheme and
- *  the legacy `rc-…` scheme (so existing ledger rows / in-flight legs and
- *  the cancelAllOrders bracket-preserve filter keep working through the
- *  transition). Returns null for non-bracket orders (so this can be called
- *  on every order Binance returns during reconciliation). */
-export declare function parseBracketCid(cid: string): {
-    bracketId: BracketId;
-    role: BracketRole;
-} | null;
-/** Cheap type-guard for "is this a reefclaw-managed bracket clientOrderId"
- *  — true for both the current and legacy schemes. */
-export declare function isBracketCid(cid: string): boolean;
-/** Venue-aware parseBracketCid — Binance's dual scheme, Hyperliquid's cloids. */
-export declare function parseBracketClientId(venue: VenueId, cid: string): {
-    bracketId: BracketId;
-    role: BracketRole;
-} | null;
-/** Venue-aware isBracketCid. */
-export declare function isBracketClientId(venue: VenueId, cid: string): boolean;

package/assets/plugin/live/bracket-id.js

@@ -1,112 +0,0 @@
-// Deterministic clientOrderId scheme for bracket orders.
-//
-// CURRENT format: bkt<16hex><role>   (20 chars, well under Binance's 36)
-//   - "bkt"      fixed prefix (no dashes — does NOT look like a tagged pair)
-//   - <16hex>    shared bracketId linking entry + SL + TP of the same trade
-//   - <role>     'e' (entry), 's' (stop-loss), 't' (take-profit)
-//
-// LEGACY format (still PARSED, never EMITTED): rc-<16hex>-<role>
-//
-//   ROOT-CAUSE FIX 2026-05-16. Controlled prod reproduction proved the
-//   recurring ~20-45s bracket cancellation is keyed to the `rc-` cid
-//   pattern: a byte-identical-shape NON-rc closePosition pair survived
-//   30+ min on the SAME symbol/window where every `rc-<16hex>-{s,t}` pair
-//   died in ~42s, `reason=none`, server-side — with the 8-surface raw-ccxt
-//   WIDE-CANCEL-TRACE silent, the skill ccxt-less, the agent issuing zero
-//   tool/exec calls, and OpenClaw having no native exchange. i.e. an
-//   actor with Binance API access, OFF this VPS and outside our software,
-//   cancels orders whose clientOrderId matches the `rc-` bracket pattern.
-//   Renaming the scheme makes our protective brackets invisible to it —
-//   exactly why every `ctp-`/`opguard-`/`mctest-` test order survived.
-//
-//   Backward compat is load-bearing: in-flight brackets + the persisted
-//   bracket-ledger.json carry LEGACY `rc-*` cids. parseBracketCid /
-//   isBracketCid MUST keep recognising them so the reconciler still tracks
-//   them and — critically — `cancelAllOrders`'s bracket-preserve filter
-//   never strips a legacy leg off a live position during the transition.
-//   Only buildBracketCid changes (emits the new scheme); legacy ages out.
-//
-// Parseability is load-bearing: on restart, the reconciler fetches open
-// orders from Binance, parses each clientOrderId, and reassembles brackets
-// from the (bracketId, role) pairs. No reliance on local state to find them.
-//
-// Binance USDⓂ-Futures newClientOrderId charset is documented as
-// ^[\.A-Z\:/a-z0-9_-]{1,36}$ — `bkt[0-9a-f]{16}[est]` (20 chars, lowercase
-// alphanumeric) is well within it. Verified vs developers.binance.com
-// USDⓂ New-Order clientOrderId filter, 2026-05-16.
-import { randomBytes } from 'node:crypto';
-import { parseHlBracketCloid, isHlBracketCloid } from '../venues/hyperliquid/hl-cloid.js';
-// Emitted scheme (no `rc-`, no dashes).
-const CID_REGEX = /^bkt([0-9a-f]{16})([est])$/;
-// Legacy scheme — still parsed for backward compat, never emitted again.
-const LEGACY_CID_REGEX = /^rc-([0-9a-f]{16})-([est])$/;
-const ROLE_TO_TAG = {
-    entry: 'e',
-    stop: 's',
-    target: 't',
-};
-const TAG_TO_ROLE = {
-    e: 'entry',
-    s: 'stop',
-    t: 'target',
-};
-/** Generate a fresh 16-char hex bracketId. */
-export function generateBracketId() {
-    return randomBytes(8).toString('hex');
-}
-/** Build a clientOrderId for a given bracket + role. Emits the CURRENT
- *  (`bkt…`) scheme only — never the legacy `rc-` scheme. */
-export function buildBracketCid(bracketId, role) {
-    if (!/^[0-9a-f]{16}$/.test(bracketId)) {
-        throw new Error(`Invalid bracketId: ${bracketId} — expected 16 hex chars`);
-    }
-    return `bkt${bracketId}${ROLE_TO_TAG[role]}`;
-}
-/** Parse a clientOrderId. Recognises BOTH the current `bkt…` scheme and
- *  the legacy `rc-…` scheme (so existing ledger rows / in-flight legs and
- *  the cancelAllOrders bracket-preserve filter keep working through the
- *  transition). Returns null for non-bracket orders (so this can be called
- *  on every order Binance returns during reconciliation). */
-export function parseBracketCid(cid) {
-    const match = CID_REGEX.exec(cid) ?? LEGACY_CID_REGEX.exec(cid);
-    if (!match)
-        return null;
-    const bracketId = match[1];
-    const tag = match[2];
-    return { bracketId, role: TAG_TO_ROLE[tag] };
-}
-/** Cheap type-guard for "is this a reefclaw-managed bracket clientOrderId"
- *  — true for both the current and legacy schemes. */
-export function isBracketCid(cid) {
-    return CID_REGEX.test(cid) || LEGACY_CID_REGEX.test(cid);
-}
-// ---- Venue-dispatched recognition (multi-venue Phase 0 seam) ----
-//
-// ALL bracket client-order-id recognition stays centralized in THIS module —
-// the brackets.md rule ("never hardcode an rc-/bkt regex elsewhere") extends
-// per-venue. Binance = the bkt/rc- schemes above. Hyperliquid = 128-bit hex
-// cloids (`0xbc7…`, hl-cloid.ts §5.7 — a Binance-style ASCII cid is not even a
-// legal HL client id). Phase 3 wires that dispatch HERE, and nowhere else.
-//
-// ★ NEITHER VENUE MAY EVER RECOGNISE THE OTHER'S SCHEME. A false positive is
-//   destructive: `cancelAllOrders` preserves anything that parses as "ours", and
-//   the reconciler cancels/re-attaches on that basis. A foreign id that parsed as
-//   ours would be treated as a protective leg we own.
-/** Venue-aware parseBracketCid — Binance's dual scheme, Hyperliquid's cloids. */
-export function parseBracketClientId(venue, cid) {
-    switch (venue) {
-        case 'binance':
-            return parseBracketCid(cid);
-        case 'hyperliquid':
-            return parseHlBracketCloid(cid);
-    }
-}
-/** Venue-aware isBracketCid. */
-export function isBracketClientId(venue, cid) {
-    switch (venue) {
-        case 'binance':
-            return isBracketCid(cid);
-        case 'hyperliquid':
-            return isHlBracketCloid(cid);
-    }
-}

package/assets/plugin/live/bracket-ledger.d.ts

@@ -1,54 +0,0 @@
-import type { BracketId, BracketLedgerEntry, BracketState } from './bracket-types.js';
-/** Canonical form for a bracket-ledger symbol key.
- *
- *  CCXT returns Binance Futures symbols as `BTC/USDT:USDT` (the `:USDT`
- *  suffix is the settlement asset); the skill + agent's tool args use the
- *  un-suffixed `BTC/USDT`. Historically we keyed the ledger by whatever the
- *  caller passed in — which produced doubled rows per symbol and caused the
- *  2026-04-21 ADA audit-vs-attach deadlock (9 of 11 symbols had both keys;
- *  see `memory/feedback_symbol_normalize_boundary.md`). This helper picks a
- *  single canonical form (un-suffixed) and is applied at every public
- *  BracketLedger entry point.
- *
- *  Matches `user-data-stream-controller.ts` and `webapp/src/lib/symbols.ts`
- *  `normalizeSymbol`, so the bracket path lines up with the WS store + UI. */
-export declare function normalizeBracketSymbol(s: string): string;
-/** Test seam — lets tests override the clock for deterministic timestamps. */
-export type NowFn = () => string;
-export declare class BracketLedger {
-    private readonly filePath;
-    private readonly dir;
-    private readonly now;
-    private entries;
-    constructor(pluginId?: string, opts?: {
-        now?: NowFn;
-        basePath?: string;
-    });
-    /** Insert or replace the entry for a symbol. Persists synchronously.
-     *  Symbol is normalized; the stored entry carries the canonical form so
-     *  later readers see it regardless of whether the caller passed suffixed
-     *  or un-suffixed input. */
-    upsert(entry: Omit<BracketLedgerEntry, 'createdAt' | 'updatedAt'> & {
-        createdAt?: string;
-        updatedAt?: string;
-    }): BracketLedgerEntry;
-    /** Mutate the state of an existing entry. Throws if entry not found. */
-    markState(symbol: string, nextState: BracketState, extras?: Partial<Pick<BracketLedgerEntry, 'attachStartedAt' | 'attachCompletedAt' | 'attachLatencyMs' | 'closedAt' | 'closeReason' | 'lastError' | 'slCid' | 'tpCid' | 'qty'>>): BracketLedgerEntry;
-    getBySymbol(symbol: string): BracketLedgerEntry | undefined;
-    getByBracketId(bracketId: BracketId): BracketLedgerEntry | undefined;
-    /** All active (non-terminal) entries. Used by reconciler + telemetry. */
-    getActive(): BracketLedgerEntry[];
-    /** Every entry in the ledger, including terminal ones (kept for audit). */
-    getAll(): BracketLedgerEntry[];
-    /** Remove an entry — typically only called for very old terminal entries
-     *  during periodic cleanup. Does NOT persist unless mutated. */
-    remove(symbol: string): boolean;
-    /** Number of entries currently in the ledger. */
-    size(): number;
-    /** Test seam — full ledger file path. */
-    getFilePath(): string;
-    private loadOrInit;
-    private persist;
-    private validateFile;
-    private validateEntry;
-}