@reefclaw/openclaw-plugin 0.1.4 → 0.1.6

package/wave9/paper-admission-guard.d.ts

@@ -0,0 +1,199 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+/** One catalog toggle represents both frozen Wave 9 strategy legs. */
+export declare const WAVE9_BUNDLE_SETUP_TYPE = "wave9_28d_momentum_reversal";
+export declare const WAVE9_MECHANICAL_EXIT_REASON = "wave9_signal_reversal";
+export type Wave9ExecutionMode = 'PAPER' | 'LIVE';
+/** Conservative shared identity check for current, legacy, or Wave 9-mission positions. */
+export declare function isWave9ManagedPosition(position: {
+    setupType?: string | null;
+    missionId?: string | null;
+}): boolean;
+export interface Wave9PaperAccountSnapshot {
+    schema: 'wave9-paper-account-v1';
+    /** Local simulator mutation stamp. It is not a cross-process lease. */
+    savedAt: number | null;
+    quoteCurrency: string;
+    wallet: Array<{
+        currency: string;
+        total: number;
+        available: number;
+        locked: number;
+    }>;
+    equityUsd: number;
+    sessionStartNavUsd: number | null;
+    positions: Array<{
+        symbol: string;
+        side: 'long' | 'short';
+        quantity: number;
+        entryPrice: number;
+        markPrice: number;
+        openedAt: string;
+        missionId: string | null;
+        setupType: string | null;
+        candidateId: string | null;
+        strategy: string | null;
+        accruedFundingUsd: number | null;
+        fundingThroughTime: string | null;
+        stopPrice: number | null;
+        initialOpenRiskUsd: number | null;
+    }>;
+    openOrders: Array<{
+        id: string;
+        symbol: string;
+        side: 'buy' | 'sell';
+        type: 'market' | 'limit';
+        amount: number;
+        filled: number;
+        price: number | null;
+    }>;
+    /** Persisted closed candidates prevent same-event replay after restart. */
+    closedWave9CandidateIds: string[];
+}
+export interface Wave9PaperAccountFingerprint {
+    fingerprint: string;
+    snapshot: Wave9PaperAccountSnapshot;
+    authoritative: false;
+    runtimeParity: false;
+    provenance: 'process_local_unlocked_simulator';
+}
+export interface Wave9PaperPositionFingerprint {
+    fingerprint: string;
+    snapshot: Omit<Wave9PaperAccountSnapshot['positions'][number], 'markPrice' | 'accruedFundingUsd' | 'fundingThroughTime'>;
+    authoritative: false;
+    runtimeParity: false;
+    provenance: 'process_local_unlocked_simulator';
+}
+export interface Wave9PaperAdmissionTokenDecision {
+    batchId: string;
+    candidateId: string;
+    missionId: string;
+    symbol: string;
+    side: 'BUY' | 'SELL';
+    /** String form preserves the exact frozen JS number across issuance. */
+    quantity: string;
+    stopPrice: string;
+    sequence: number;
+    notBeforeMs: number;
+    deadlineMs: number;
+    accountFingerprint: string;
+    tradingMode: Wave9ExecutionMode;
+}
+export interface Wave9IssuedAdmission {
+    token: string;
+    batchId: string;
+    candidateId: string;
+    missionId: string;
+    sequence: number;
+    deadlineMs: number;
+    accountFingerprint: string;
+    tradingMode: Wave9ExecutionMode;
+}
+export interface Wave9PaperExitTokenDecision {
+    candidateId: string;
+    missionId: string;
+    symbol: string;
+    positionSide: 'long' | 'short';
+    reason: 'signal_reversal';
+    notBeforeMs: number;
+    deadlineMs: number;
+    positionFingerprint: string;
+    tradingMode: Wave9ExecutionMode;
+}
+export interface Wave9IssuedExit {
+    token: string;
+    candidateId: string;
+    missionId: string;
+    deadlineMs: number;
+    positionFingerprint: string;
+    tradingMode: Wave9ExecutionMode;
+}
+export interface Wave9EntryAuthorizationRequest {
+    token: string;
+    candidateId: string;
+    missionId: string;
+    symbol: string;
+    side: string;
+    type: string;
+    quantity: number;
+    stopPrice: number | undefined;
+    setupType: string | undefined;
+    accountFingerprint: string;
+    tradingMode: Wave9ExecutionMode;
+}
+export interface Wave9ExitAuthorizationRequest {
+    token: string;
+    candidateId: string;
+    missionId: string;
+    symbol: string;
+    positionSide: 'long' | 'short';
+    setupType: string | undefined;
+    reason: string | undefined;
+    positionFingerprint: string;
+    tradingMode: Wave9ExecutionMode;
+}
+export interface Wave9AuthorizationLease {
+    readonly leaseId: string;
+    readonly kind: 'entry' | 'exit';
+    readonly token: string;
+}
+export declare class Wave9PaperAdmissionGuardError extends Error {
+    constructor(message: string);
+}
+export interface Wave9PaperAdmissionGuardOptions {
+    now?: () => number;
+    /** Opaque-token lifetime, bounded again by the decision's hard deadline. */
+    tokenTtlMs?: number;
+}
+/**
+ * Capture the complete process-local book inputs used to defend a Wave 9
+ * admission against local TOCTOU. This is deliberately labelled non-
+ * authoritative: the production paper deployment has no cross-process owner
+ * lease, so a matching hash is useful fail-closed protection, never parity or
+ * promotion evidence.
+ */
+export declare function captureWave9PaperAccountSnapshot(adapter: IExchangeAdapter): Wave9PaperAccountFingerprint;
+/** Stable held-position identity for a mechanical reversal close. */
+export declare function captureWave9PaperPositionFingerprint(adapter: IExchangeAdapter, symbol: string): Wave9PaperPositionFingerprint;
+/** In-memory capability guard shared by get_wave9_status and mutation tools. */
+export declare class Wave9PaperAdmissionGuard {
+    private readonly now;
+    private readonly tokenTtlMs;
+    private readonly batches;
+    private readonly events;
+    private readonly entriesByToken;
+    private readonly exitsByIdentity;
+    private readonly exitsByToken;
+    constructor(options?: Wave9PaperAdmissionGuardOptions);
+    issueBatch(decisions: readonly Wave9PaperAdmissionTokenDecision[]): Wave9IssuedAdmission[];
+    issueExitBatch(decisions: readonly Wave9PaperExitTokenDecision[]): Wave9IssuedExit[];
+    beginEntry(request: Wave9EntryAuthorizationRequest): Wave9AuthorizationLease;
+    beginExit(request: Wave9ExitAuthorizationRequest): Wave9AuthorizationLease;
+    revalidate(lease: Wave9AuthorizationLease, fingerprint: string): void;
+    commit(lease: Wave9AuthorizationLease): void;
+    /**
+     * Consume a failed capability. Entry failure latches the whole projected
+     * batch because later sizing assumed every earlier accepted entry. Exit
+     * retry is allowed when the caller explicitly proves another attempt stays
+     * risk-reducing, including a residual/unknown result after a reduce-only
+     * LIVE close submission.
+     */
+    abort(lease: Wave9AuthorizationLease, reason: string, options?: {
+        retryable?: boolean;
+        latchEvent?: boolean;
+    }): void;
+    private validateWindow;
+    private newEntryRecord;
+    private newExitRecord;
+    private rotateEntryToken;
+    private rotateExitToken;
+    private newToken;
+    private validateTokenShape;
+    private assertUsable;
+    private lease;
+    private recordForLease;
+    private assertFingerprint;
+    private sameEntryDecision;
+    private validateExitDecision;
+    private exitIdentity;
+    private sameExitDecision;
+}