@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/venues/symbols.d.ts

@@ -0,0 +1,43 @@
+export type VenueId = 'binance' | 'hyperliquid';
+export declare const VENUE_IDS: readonly VenueId[];
+export declare function isVenueId(value: unknown): value is VenueId;
+/** Parse a raw config value into a venue.
+ *  Absent/empty → 'binance' (every pre-venue config file keeps today's
+ *  behavior byte-identically). An unrecognized string is surfaced to the
+ *  caller instead of being silently coerced — mis-spelling a venue must be
+ *  loud, never quietly become "trade on Binance". */
+export declare function parseVenue(raw: unknown): {
+    venue: VenueId;
+    unrecognized?: string;
+};
+/** `FillEvent.exchange` / webapp `trades.exchange` value — half of the
+ *  audit-trail idempotency key `(exchange, exchange_trade_id)` (migration
+ *  0042). 'binance_futures' is the historical literal on every existing row;
+ *  NEVER change these strings once a venue has written rows. */
+export declare const FILL_EXCHANGE_ID: Record<VenueId, string>;
+export declare function fillExchangeId(venue: VenueId): string;
+/** Quote/settle asset of the venue's linear perps. */
+export declare const VENUE_QUOTE_ASSET: Record<VenueId, string>;
+/** Prefix that namespaces Hyperliquid rows inside the intel symbol column. */
+export declare const HL_INTEL_PREFIX = "HL_";
+/** Canonical symbol → the venue's CCXT unified symbol.
+ *  'BTC/USDT' (binance) → 'BTC/USDT:USDT'; 'BTC/USDC' (hyperliquid) →
+ *  'BTC/USDC:USDC'. Accepts an already-suffixed input (idempotent). */
+export declare function toCcxtSymbol(venue: VenueId, canonical: string): string;
+/** Canonical symbol → intel DB symbol.
+ *  binance: 'BTC/USDT' → 'BTCUSDT' (the historical concatenated form intel has
+ *  always stored); hyperliquid: 'BTC/USDC' → 'HL_BTC' (namespaced coin, case
+ *  preserved). */
+export declare function toIntelSymbol(venue: VenueId, canonical: string): string;
+/** Inverse of toIntelSymbol. 'HL_'-prefixed → hyperliquid; everything else is
+ *  the historical Binance namespace. Binance symbols that are not
+ *  USDT-concatenated (none exist in INTEL_SYMBOLS today) come back verbatim as
+ *  canonical — honest passthrough, not a guess. */
+export declare function fromIntelSymbol(intelSymbol: string): {
+    venue: VenueId;
+    canonical: string;
+};
+/** The Hyperliquid venue-native coin name for a canonical symbol
+ *  ('BTC/USDC' → 'BTC'). Orders address assets by integer index resolved from
+ *  `meta.universe` at runtime — the coin name is the stable half. */
+export declare function toHyperliquidCoin(canonical: string): string;

package/venues/symbols.js

@@ -0,0 +1,107 @@
+// ⚠️ GENERATED FILE — DO NOT EDIT.
+// Canonical source of truth: shared/src/venues/symbols.ts
+// Regenerate: node scripts/sync-shared-code.mjs  (enforced by shared-code-sync.test.ts)
+//
+// This copy exists because this package builds with tsc and deploys as a
+// self-contained tree that strips workspace deps, so it cannot import
+// @reefclaw/shared runtime code across the deploy boundary.
+export const VENUE_IDS = ['binance', 'hyperliquid'];
+export function isVenueId(value) {
+    return value === 'binance' || value === 'hyperliquid';
+}
+/** Parse a raw config value into a venue.
+ *  Absent/empty → 'binance' (every pre-venue config file keeps today's
+ *  behavior byte-identically). An unrecognized string is surfaced to the
+ *  caller instead of being silently coerced — mis-spelling a venue must be
+ *  loud, never quietly become "trade on Binance". */
+export function parseVenue(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return { venue: 'binance' };
+    if (isVenueId(raw))
+        return { venue: raw };
+    return { venue: 'binance', unrecognized: String(raw) };
+}
+/** `FillEvent.exchange` / webapp `trades.exchange` value — half of the
+ *  audit-trail idempotency key `(exchange, exchange_trade_id)` (migration
+ *  0042). 'binance_futures' is the historical literal on every existing row;
+ *  NEVER change these strings once a venue has written rows. */
+export const FILL_EXCHANGE_ID = {
+    binance: 'binance_futures',
+    hyperliquid: 'hyperliquid',
+};
+export function fillExchangeId(venue) {
+    return FILL_EXCHANGE_ID[venue];
+}
+/** Quote/settle asset of the venue's linear perps. */
+export const VENUE_QUOTE_ASSET = {
+    binance: 'USDT',
+    hyperliquid: 'USDC',
+};
+/** Prefix that namespaces Hyperliquid rows inside the intel symbol column. */
+export const HL_INTEL_PREFIX = 'HL_';
+/** Strip a CCXT settle suffix ('BTC/USDT:USDT' → 'BTC/USDT'). Same regex as
+ *  webapp/src/lib/symbols.ts normalizeSymbol — kept inline so this module has
+ *  zero imports and survives the sync-copy deploy boundary. */
+function stripSettleSuffix(symbol) {
+    return symbol.replace(/:[A-Z]+$/, '');
+}
+function splitCanonical(canonical) {
+    const stripped = stripSettleSuffix(canonical.trim());
+    const parts = stripped.split('/');
+    if (parts.length !== 2 || parts[0].length === 0 || parts[1].length === 0) {
+        throw new Error(`Not a canonical BASE/QUOTE symbol: '${canonical}'`);
+    }
+    return { base: parts[0], quote: parts[1] };
+}
+/** Canonical symbol → the venue's CCXT unified symbol.
+ *  'BTC/USDT' (binance) → 'BTC/USDT:USDT'; 'BTC/USDC' (hyperliquid) →
+ *  'BTC/USDC:USDC'. Accepts an already-suffixed input (idempotent). */
+export function toCcxtSymbol(venue, canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (quote !== VENUE_QUOTE_ASSET[venue]) {
+        throw new Error(`Symbol '${canonical}' is not ${VENUE_QUOTE_ASSET[venue]}-quoted — not a ${venue} linear perp`);
+    }
+    return `${base}/${quote}:${quote}`;
+}
+/** Canonical symbol → intel DB symbol.
+ *  binance: 'BTC/USDT' → 'BTCUSDT' (the historical concatenated form intel has
+ *  always stored); hyperliquid: 'BTC/USDC' → 'HL_BTC' (namespaced coin, case
+ *  preserved). */
+export function toIntelSymbol(venue, canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (venue === 'hyperliquid') {
+        if (quote !== VENUE_QUOTE_ASSET.hyperliquid) {
+            throw new Error(`Symbol '${canonical}' is not USDC-quoted — not a Hyperliquid perp`);
+        }
+        return `${HL_INTEL_PREFIX}${base}`;
+    }
+    return `${base}${quote}`;
+}
+/** Inverse of toIntelSymbol. 'HL_'-prefixed → hyperliquid; everything else is
+ *  the historical Binance namespace. Binance symbols that are not
+ *  USDT-concatenated (none exist in INTEL_SYMBOLS today) come back verbatim as
+ *  canonical — honest passthrough, not a guess. */
+export function fromIntelSymbol(intelSymbol) {
+    if (intelSymbol.startsWith(HL_INTEL_PREFIX)) {
+        const coin = intelSymbol.slice(HL_INTEL_PREFIX.length);
+        if (coin.length === 0) {
+            throw new Error(`Malformed intel symbol '${intelSymbol}' — empty coin after HL_ prefix`);
+        }
+        return { venue: 'hyperliquid', canonical: `${coin}/${VENUE_QUOTE_ASSET.hyperliquid}` };
+    }
+    if (intelSymbol.endsWith(VENUE_QUOTE_ASSET.binance) && intelSymbol.length > 4) {
+        const base = intelSymbol.slice(0, -VENUE_QUOTE_ASSET.binance.length);
+        return { venue: 'binance', canonical: `${base}/${VENUE_QUOTE_ASSET.binance}` };
+    }
+    return { venue: 'binance', canonical: intelSymbol };
+}
+/** The Hyperliquid venue-native coin name for a canonical symbol
+ *  ('BTC/USDC' → 'BTC'). Orders address assets by integer index resolved from
+ *  `meta.universe` at runtime — the coin name is the stable half. */
+export function toHyperliquidCoin(canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (quote !== VENUE_QUOTE_ASSET.hyperliquid) {
+        throw new Error(`Symbol '${canonical}' is not USDC-quoted — not a Hyperliquid perp`);
+    }
+    return base;
+}

package/wave9/live-account-capture.d.ts

@@ -0,0 +1,67 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import { type Wave9ExecutionMode } from './paper-admission-guard.js';
+import { type Wave9LiveExecutionLedger } from './live-execution-ledger.js';
+export interface Wave9NativeStopObservation {
+    verified: boolean;
+    reason: string;
+    bracketId: string | null;
+    bracketState: string | null;
+    entryClientOrderId: string | null;
+    stopClientOrderId: string | null;
+    exchangeOrderId: string | null;
+    entrySide: 'buy' | 'sell' | null;
+    stopSide: 'buy' | 'sell' | null;
+    stopPrice: number | null;
+    bracketQuantity: number | null;
+    closePosition: boolean | null;
+    liveness: 'live' | 'terminal' | 'unknown' | null;
+}
+export interface Wave9LiveStopConfirmationInput {
+    candidateId: string;
+    symbol: string;
+    entryClientOrderId: string;
+    entrySide: 'buy' | 'sell';
+    stopPrice: number;
+    filledQuantity: number;
+}
+export interface Wave9LiveObservedPosition {
+    symbol: string;
+    side: 'long' | 'short';
+    quantity: number;
+    entryPrice: number;
+    markPrice: number;
+    stopPrice?: number;
+    missionId?: string;
+    setupType?: string;
+    candidateId?: string;
+    strategy?: 'tsmom_28d_long_flat_reversal_1d' | 'tsmom_28d_short_flat_reversal_1d';
+    accruedFundingUsd?: number;
+    openedAt?: string;
+    initialStopPrice?: number;
+    nativeStop?: Wave9NativeStopObservation;
+    positionFingerprint?: string;
+}
+export interface Wave9LiveAccountCapture {
+    fingerprint: string;
+    cashEquityUsd: number;
+    positions: Wave9LiveObservedPosition[];
+    pendingExposureOrderCount: number;
+    executedCandidateIds: string[];
+    nativeStopProtectionComplete: boolean;
+    nativeStopIssues: string[];
+    authoritative: true;
+    runtimeParity: false;
+    provenance: 'live_exchange_structural_snapshot_and_durable_wave9_ledger';
+}
+/** One-shot post-fill confirmation used after the bracket row becomes active. */
+export declare function confirmWave9LiveNativeStop(adapter: IExchangeAdapter, input: Wave9LiveStopConfirmationInput): Promise<boolean>;
+/**
+ * Capture exchange-authoritative LIVE geometry without volatile mark prices in
+ * the authorization fingerprint. Wallet cash, positions, pending
+ * exposure-increasing orders, and durable Wave 9 identities are all bound.
+ */
+export declare function captureWave9LiveAccount(adapter: IExchangeAdapter, ledger: Wave9LiveExecutionLedger, mode: Wave9ExecutionMode): Promise<Wave9LiveAccountCapture>;
+export declare function captureWave9LivePosition(adapter: IExchangeAdapter, ledger: Wave9LiveExecutionLedger, mode: Wave9ExecutionMode, symbol: string): Promise<{
+    fingerprint: string;
+    position: Wave9LiveObservedPosition;
+}>;

package/wave9/live-account-capture.js

@@ -0,0 +1,435 @@
+import { createHash } from 'node:crypto';
+import { getQuoteWalletBalance } from '../balance-utils.js';
+import { parseBracketCid } from '../live/bracket-id.js';
+import { WAVE9_BUNDLE_SETUP_TYPE, } from './paper-admission-guard.js';
+import { wave9ClientOrderId, } from './live-execution-ledger.js';
+function canonicalSymbol(symbol) {
+    return symbol.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+}
+function finitePositive(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`Wave 9 live snapshot requires positive ${label}`);
+    }
+    return value;
+}
+function nearlyEqual(left, right) {
+    return Math.abs(left - right) <= 1e-9 * Math.max(1, Math.abs(left), Math.abs(right));
+}
+/**
+ * Binance may tick-normalize the submitted trigger while the local bracket
+ * row retains the requested ATR-derived value. One basis point matches the
+ * existing bracket idempotency tolerance, admits normal tick rounding, and
+ * still rejects any materially different stop.
+ */
+function exchangeStopPriceMatches(actual, requested) {
+    return Math.abs(actual - requested)
+        <= Math.max(1e-12, Math.abs(requested) * 1e-4);
+}
+function asNativeStopAdapter(adapter) {
+    const candidate = adapter;
+    return typeof candidate.getBracketLedger === 'function'
+        && typeof candidate.resolveBracketLegLiveness === 'function'
+        ? candidate
+        : null;
+}
+function openWave9Record(ledger, symbol, side) {
+    const canonical = canonicalSymbol(symbol);
+    const orderSide = side === 'long' ? 'buy' : 'sell';
+    const matches = ledger.getAll().filter((record) => record.state === 'open'
+        && record.symbol === canonical
+        && record.side === orderSide);
+    matches.sort((left, right) => right.updatedAt - left.updatedAt || right.candidateId.localeCompare(left.candidateId));
+    return matches[0];
+}
+function emptyStopObservation(reason) {
+    return {
+        verified: false,
+        reason,
+        bracketId: null,
+        bracketState: null,
+        entryClientOrderId: null,
+        stopClientOrderId: null,
+        exchangeOrderId: null,
+        entrySide: null,
+        stopSide: null,
+        stopPrice: null,
+        bracketQuantity: null,
+        closePosition: null,
+        liveness: null,
+    };
+}
+function rawOrderField(order, key) {
+    const direct = order.info?.[key];
+    if (direct !== undefined)
+        return direct;
+    const nested = order.info?.info;
+    return typeof nested === 'object' && nested !== null && !Array.isArray(nested)
+        ? nested[key]
+        : undefined;
+}
+function boolField(value) {
+    if (value === true || value === 'true' || value === 'TRUE')
+        return true;
+    if (value === false || value === 'false' || value === 'FALSE')
+        return false;
+    return null;
+}
+function finiteOrderStopPrice(order) {
+    if (!order)
+        return null;
+    const candidates = [order.price, rawOrderField(order, 'triggerPrice'), rawOrderField(order, 'stopPrice')];
+    for (const value of candidates) {
+        const parsed = typeof value === 'number' ? value : Number(value);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return null;
+}
+function proofLiveness(proof) {
+    if (!proof)
+        return 'unknown';
+    if (proof.algoStatus === 'NEW'
+        || proof.algoStatus === 'WORKING'
+        || proof.algoStatus === 'TRIGGERING')
+        return 'live';
+    if (proof.algoStatus === 'TRIGGERED'
+        || proof.algoStatus === 'CANCELED'
+        || proof.algoStatus === 'FINISHED'
+        || proof.algoStatus === 'EXPIRED'
+        || proof.algoStatus === 'REJECTED')
+        return 'terminal';
+    return 'unknown';
+}
+/**
+ * Bind one durable Wave 9 execution identity to the exact exchange-native
+ * stop currently protecting it. A failed observation remains structural data
+ * (so ownership/reversal handling survives) but can never authorize admission.
+ */
+async function observeNativeStop(adapter, openOrders, expectation) {
+    const native = asNativeStopAdapter(adapter);
+    if (!native)
+        return emptyStopObservation('native_stop_adapter_unavailable');
+    const bracket = native.getBracketLedger()?.getBySymbol(expectation.symbol);
+    if (!bracket)
+        return emptyStopObservation('native_stop_ledger_row_missing');
+    const stopOrders = bracket.slCid
+        ? openOrders.filter((order) => order.clientOrderId === bracket.slCid)
+        : [];
+    const stopOrder = stopOrders.length === 1 ? stopOrders[0] : undefined;
+    const directProofRequired = !expectation.requireExchangeOrderDetails;
+    let directProof = null;
+    let liveness = null;
+    if (bracket.slCid) {
+        if (directProofRequired) {
+            try {
+                directProof = await native.resolveBracketLegProof?.(bracket.slCid) ?? null;
+            }
+            catch {
+                directProof = null;
+            }
+            liveness = proofLiveness(directProof);
+        }
+        else {
+            try {
+                liveness = await native.resolveBracketLegLiveness(bracket.slCid);
+            }
+            catch {
+                liveness = 'unknown';
+            }
+        }
+    }
+    const exchangeStopPrice = directProofRequired
+        ? directProof?.triggerPrice ?? null
+        : finiteOrderStopPrice(stopOrder);
+    const closePosition = directProofRequired
+        ? directProof?.closePosition ?? null
+        : stopOrder ? boolField(rawOrderField(stopOrder, 'closePosition')) : null;
+    const exchangeSymbol = directProofRequired ? directProof?.symbol : stopOrder?.symbol;
+    const exchangeSide = directProofRequired ? directProof?.side : stopOrder?.side;
+    const orderType = directProofRequired
+        ? directProof?.orderType ?? ''
+        : stopOrder ? String(rawOrderField(stopOrder, 'orderType') ?? '').toUpperCase() : '';
+    const observation = {
+        verified: false,
+        reason: 'native_stop_unverified',
+        bracketId: bracket.bracketId,
+        bracketState: bracket.state,
+        entryClientOrderId: bracket.entryCid,
+        stopClientOrderId: bracket.slCid ?? null,
+        exchangeOrderId: directProofRequired ? directProof?.algoId ?? null : stopOrder?.id ?? null,
+        entrySide: bracket.entrySide,
+        stopSide: exchangeSide ?? null,
+        stopPrice: exchangeStopPrice ?? (Number.isFinite(bracket.stopPrice) ? bracket.stopPrice : null),
+        bracketQuantity: Number.isFinite(bracket.qty) ? bracket.qty : null,
+        closePosition,
+        liveness,
+    };
+    const parsedStopCid = bracket.slCid ? parseBracketCid(bracket.slCid) : null;
+    const expectedStopSide = expectation.entrySide === 'buy' ? 'sell' : 'buy';
+    const expectedEntryCid = wave9ClientOrderId(expectation.candidateId);
+    const quantityTolerance = 1e-9 * Math.max(1, expectation.currentPositionQuantity, expectation.filledQuantity, typeof bracket.qty === 'number' ? Math.abs(bracket.qty) : 0);
+    const exactCurrentQuantity = nearlyEqual(expectation.currentPositionQuantity, expectation.filledQuantity);
+    const bracketQuantityValid = typeof bracket.qty === 'number'
+        && Number.isFinite(bracket.qty)
+        && bracket.qty > 0
+        && (expectation.requireExactPositionQuantity
+            ? nearlyEqual(bracket.qty, expectation.filledQuantity)
+            : bracket.qty + quantityTolerance >= expectation.currentPositionQuantity
+                && bracket.qty <= expectation.filledQuantity + quantityTolerance);
+    if (expectation.entryClientOrderId !== expectedEntryCid) {
+        observation.reason = 'expected_entry_client_order_id_is_not_candidate_bound';
+    }
+    else if (bracket.state !== 'active' && bracket.state !== 'partial') {
+        observation.reason = 'native_stop_bracket_not_active';
+    }
+    else if (bracket.entryCid !== expectation.entryClientOrderId) {
+        observation.reason = 'native_stop_entry_client_order_id_mismatch';
+    }
+    else if (bracket.entrySide !== expectation.entrySide) {
+        observation.reason = 'native_stop_entry_side_mismatch';
+    }
+    else if (!bracket.slCid || parsedStopCid?.role !== 'stop'
+        || parsedStopCid.bracketId !== bracket.bracketId) {
+        observation.reason = 'native_stop_client_order_id_invalid';
+    }
+    else if (typeof bracket.stopPrice !== 'number'
+        || !Number.isFinite(bracket.stopPrice)
+        || !nearlyEqual(bracket.stopPrice, expectation.stopPrice)) {
+        observation.reason = 'native_stop_ledger_price_mismatch';
+    }
+    else if (expectation.currentPositionQuantity
+        > expectation.filledQuantity + quantityTolerance
+        || (expectation.requireExactPositionQuantity && !exactCurrentQuantity)) {
+        observation.reason = 'native_stop_position_quantity_not_covered';
+    }
+    else if (!bracketQuantityValid) {
+        observation.reason = 'native_stop_bracket_quantity_mismatch';
+    }
+    else if (directProofRequired && !directProof) {
+        observation.reason = 'native_stop_exact_exchange_proof_unavailable';
+    }
+    else if (directProofRequired && directProof?.clientAlgoId !== bracket.slCid) {
+        observation.reason = 'native_stop_exact_exchange_identity_mismatch';
+    }
+    else if (liveness !== 'live') {
+        observation.reason = 'native_stop_exchange_liveness_unverified';
+    }
+    else if (!directProofRequired
+        && (stopOrders.length !== 1 || !stopOrder || stopOrder.status !== 'open')) {
+        observation.reason = 'native_stop_exchange_order_missing';
+    }
+    else if (!exchangeSymbol
+        || canonicalSymbol(exchangeSymbol) !== canonicalSymbol(expectation.symbol)) {
+        observation.reason = 'native_stop_exchange_symbol_mismatch';
+    }
+    else if (exchangeSide !== expectedStopSide) {
+        observation.reason = 'native_stop_exchange_side_mismatch';
+    }
+    else if (orderType !== 'STOP_MARKET') {
+        observation.reason = 'native_stop_exchange_type_mismatch';
+    }
+    else if (exchangeStopPrice === null
+        || !exchangeStopPriceMatches(exchangeStopPrice, expectation.stopPrice)) {
+        observation.reason = 'native_stop_exchange_price_mismatch';
+    }
+    else if (closePosition !== true) {
+        observation.reason = 'native_stop_is_not_close_all_position';
+    }
+    else {
+        observation.verified = true;
+        observation.reason = 'verified_exchange_native_close_all_stop';
+    }
+    return observation;
+}
+/** One-shot post-fill confirmation used after the bracket row becomes active. */
+export async function confirmWave9LiveNativeStop(adapter, input) {
+    if (!adapter.isLive || adapter.mode !== 'LIVE' || adapter.readiness !== 'READY')
+        return false;
+    const observation = await observeNativeStop(adapter, [], {
+        ...input,
+        currentPositionQuantity: input.filledQuantity,
+        requireExactPositionQuantity: true,
+        requireExchangeOrderDetails: false,
+    });
+    return observation.verified;
+}
+function validatePositions(positions) {
+    for (const position of positions) {
+        if (typeof position.symbol !== 'string' || position.symbol.length === 0) {
+            throw new Error('Wave 9 live snapshot contains a malformed position symbol');
+        }
+        if (position.side !== 'long' && position.side !== 'short') {
+            throw new Error(`Wave 9 live snapshot contains a malformed ${position.symbol} side`);
+        }
+        if (typeof position.contracts !== 'number'
+            || !Number.isFinite(position.contracts)
+            || position.contracts < 0) {
+            throw new Error(`Wave 9 live snapshot contains malformed ${position.symbol} contracts`);
+        }
+    }
+}
+function isProtectiveOrder(order) {
+    if (order.clientOrderId) {
+        const parsed = parseBracketCid(order.clientOrderId);
+        if (parsed?.role === 'stop' || parsed?.role === 'target')
+            return true;
+    }
+    const info = order.info ?? {};
+    if (info.reduceOnly === true || info.closePosition === true)
+        return true;
+    const orderType = String(info.orderType ?? info.type ?? '').toUpperCase();
+    return Boolean((orderType === 'STOP_MARKET' || orderType === 'TAKE_PROFIT_MARKET')
+        && (info.closePosition === true || info.reduceOnly === true));
+}
+function structuralPosition(position) {
+    return {
+        symbol: canonicalSymbol(position.symbol),
+        side: position.side,
+        contracts: position.contracts,
+        entryPrice: position.entryPrice,
+    };
+}
+function structuralOrder(order) {
+    return {
+        id: order.id,
+        clientOrderId: order.clientOrderId ?? null,
+        symbol: canonicalSymbol(order.symbol),
+        side: order.side,
+        type: order.type,
+        amount: order.amount,
+        filled: order.filled,
+        price: order.price,
+    };
+}
+function positionFingerprint(position) {
+    const structural = {
+        symbol: canonicalSymbol(position.symbol),
+        side: position.side,
+        quantity: position.quantity,
+        entryPrice: position.entryPrice,
+        stopPrice: position.stopPrice ?? null,
+        missionId: position.missionId ?? null,
+        setupType: position.setupType ?? null,
+        candidateId: position.candidateId ?? null,
+        strategy: position.strategy ?? null,
+        openedAt: position.openedAt ?? null,
+        nativeStop: position.nativeStop ?? null,
+    };
+    return createHash('sha256').update(JSON.stringify(structural)).digest('hex');
+}
+/**
+ * Capture exchange-authoritative LIVE geometry without volatile mark prices in
+ * the authorization fingerprint. Wallet cash, positions, pending
+ * exposure-increasing orders, and durable Wave 9 identities are all bound.
+ */
+export async function captureWave9LiveAccount(adapter, ledger, mode) {
+    if (!adapter.isLive || mode !== 'LIVE' || adapter.mode !== 'LIVE') {
+        throw new Error('Wave 9 live snapshot requires a LIVE adapter in LIVE mode');
+    }
+    if (adapter.readiness !== 'READY') {
+        throw new Error(`Wave 9 live snapshot requires adapter READY (got ${adapter.readiness})`);
+    }
+    const [balance, positions, openOrders] = await Promise.all([
+        adapter.getBalance(),
+        adapter.getPositionsOrNull(),
+        adapter.getOpenOrders(),
+    ]);
+    if (positions === null) {
+        throw new Error('Wave 9 live position snapshot is unavailable');
+    }
+    validatePositions(positions);
+    const cashEquityUsd = finitePositive(getQuoteWalletBalance(balance), 'wallet cash');
+    const pendingExposureOrders = openOrders
+        .filter((order) => order.status === 'open' && !isProtectiveOrder(order))
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const observed = await Promise.all(positions
+        .filter((position) => Number.isFinite(position.contracts) && position.contracts > 0)
+        .map(async (position) => {
+        const record = openWave9Record(ledger, position.symbol, position.side);
+        const row = {
+            symbol: position.symbol,
+            side: position.side,
+            quantity: finitePositive(position.contracts, `${position.symbol} contracts`),
+            entryPrice: finitePositive(position.entryPrice, `${position.symbol} entry price`),
+            markPrice: finitePositive(position.markPrice, `${position.symbol} mark price`),
+        };
+        if (!record)
+            return row;
+        const nativeStop = await observeNativeStop(adapter, openOrders, {
+            candidateId: record.candidateId,
+            symbol: position.symbol,
+            entryClientOrderId: record.clientOrderId,
+            entrySide: record.side,
+            stopPrice: record.initialStop,
+            filledQuantity: record.filledQuantity ?? record.quantity,
+            currentPositionQuantity: position.contracts,
+            requireExactPositionQuantity: false,
+            requireExchangeOrderDetails: true,
+        });
+        row.initialStopPrice = record.initialStop;
+        if (nativeStop.stopPrice !== null)
+            row.stopPrice = nativeStop.stopPrice;
+        row.missionId = record.missionId;
+        row.setupType = WAVE9_BUNDLE_SETUP_TYPE;
+        row.candidateId = record.candidateId;
+        row.strategy = record.strategy;
+        row.accruedFundingUsd = 0;
+        row.openedAt = new Date(record.openedAt ?? record.attemptedAt).toISOString();
+        row.nativeStop = nativeStop;
+        row.positionFingerprint = positionFingerprint(row);
+        return row;
+    }));
+    observed
+        .sort((left, right) => canonicalSymbol(left.symbol).localeCompare(canonicalSymbol(right.symbol)));
+    const executedCandidateIds = ledger.getExecutedCandidateIds().sort((a, b) => a.localeCompare(b));
+    const ownedPositions = observed.filter((position) => position.candidateId);
+    const nativeStopIssues = ownedPositions
+        .filter((position) => position.nativeStop?.verified !== true)
+        .map((position) => `${position.candidateId}:${position.nativeStop?.reason ?? 'native_stop_missing'}`)
+        .sort((left, right) => left.localeCompare(right));
+    const structural = {
+        schema: 'wave9-live-account-v1',
+        mode,
+        walletCashUsd: cashEquityUsd,
+        positions: positions
+            .filter((position) => Number.isFinite(position.contracts) && position.contracts > 0)
+            .map(structuralPosition)
+            .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right))),
+        pendingExposureOrders: pendingExposureOrders.map(structuralOrder),
+        wave9Identities: ledger.getAll().map((record) => ({
+            candidateId: record.candidateId,
+            missionId: record.missionId,
+            symbol: record.symbol,
+            side: record.side,
+            quantity: record.quantity,
+            initialStop: record.initialStop,
+            state: record.state,
+        })),
+        wave9NativeStops: ownedPositions.map((position) => ({
+            candidateId: position.candidateId,
+            nativeStop: position.nativeStop ?? null,
+        })),
+        executedCandidateIds,
+    };
+    return {
+        fingerprint: createHash('sha256').update(JSON.stringify(structural)).digest('hex'),
+        cashEquityUsd,
+        positions: observed,
+        pendingExposureOrderCount: pendingExposureOrders.length,
+        executedCandidateIds,
+        nativeStopProtectionComplete: nativeStopIssues.length === 0,
+        nativeStopIssues,
+        authoritative: true,
+        runtimeParity: false,
+        provenance: 'live_exchange_structural_snapshot_and_durable_wave9_ledger',
+    };
+}
+export async function captureWave9LivePosition(adapter, ledger, mode, symbol) {
+    const account = await captureWave9LiveAccount(adapter, ledger, mode);
+    const canonical = canonicalSymbol(symbol);
+    const matches = account.positions.filter((position) => canonicalSymbol(position.symbol) === canonical && position.candidateId);
+    if (matches.length !== 1 || !matches[0].positionFingerprint) {
+        throw new Error(`Wave 9 live position snapshot requires exactly one durable ${canonical} position`);
+    }
+    return { fingerprint: matches[0].positionFingerprint, position: matches[0] };
+}