@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/wave9/paper-admission-guard.js

@@ -0,0 +1,650 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { WAVE9_SYMBOL_PRIORITY } from '../portfolio/wave9-policy.js';
+/** One catalog toggle represents both frozen Wave 9 strategy legs. */
+export const WAVE9_BUNDLE_SETUP_TYPE = 'wave9_28d_momentum_reversal';
+export const WAVE9_MECHANICAL_EXIT_REASON = 'wave9_signal_reversal';
+/** Conservative shared identity check for current, legacy, or Wave 9-mission positions. */
+export function isWave9ManagedPosition(position) {
+    return position.setupType === WAVE9_BUNDLE_SETUP_TYPE
+        || position.setupType === 'wave9_daily_tsmom'
+        || position.missionId?.startsWith('wave9_') === true;
+}
+const TOKEN_PATTERN = /^w9[ex]_[A-Za-z0-9_-]{43}$/;
+const FINGERPRINT_PATTERN = /^[a-f0-9]{64}$/;
+const DECIMAL_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+const MAX_ID_LENGTH = 512;
+export class Wave9PaperAdmissionGuardError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'Wave9PaperAdmissionGuardError';
+    }
+}
+function canonicalSymbol(symbol) {
+    return symbol.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+}
+function requireFinite(value, label) {
+    if (!Number.isFinite(value))
+        throw new Wave9PaperAdmissionGuardError(`${label} must be finite`);
+}
+function finiteOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function exactPositiveNumber(value, label) {
+    if (typeof value !== 'string' || !DECIMAL_PATTERN.test(value)) {
+        throw new Wave9PaperAdmissionGuardError(`${label} must be an exact decimal string`);
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0 || String(parsed) !== value) {
+        throw new Wave9PaperAdmissionGuardError(`${label} must be the canonical string form of a positive finite number`);
+    }
+    return parsed;
+}
+function exactText(value, label) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > MAX_ID_LENGTH || value.trim() !== value) {
+        throw new Wave9PaperAdmissionGuardError(`${label} is malformed`);
+    }
+}
+function requireExecutionMode(value) {
+    if (value !== 'PAPER' && value !== 'LIVE') {
+        throw new Wave9PaperAdmissionGuardError('Wave 9 execution mode must be PAPER or LIVE');
+    }
+}
+function sameSecret(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function stableMissionId(candidateId) {
+    return `wave9_${createHash('sha256').update(candidateId).digest('hex').slice(0, 32)}`;
+}
+function parseEntryCandidate(decision) {
+    const parts = decision.candidateId.split('|');
+    if (parts.length !== 4)
+        throw new Wave9PaperAdmissionGuardError('candidateId is not a frozen Wave 9 identity');
+    const [eventTime, symbol, strategy, direction] = parts;
+    const eventMs = Date.parse(eventTime);
+    if (!Number.isFinite(eventMs) || new Date(eventMs).toISOString() !== eventTime) {
+        throw new Wave9PaperAdmissionGuardError('candidateId event time is not canonical ISO');
+    }
+    if (symbol !== decision.symbol || !['LONG', 'SHORT'].includes(direction)) {
+        throw new Wave9PaperAdmissionGuardError('candidateId does not match symbol/direction');
+    }
+    if ((direction === 'LONG' && strategy !== 'tsmom_28d_long_flat_reversal_1d')
+        || (direction === 'SHORT' && strategy !== 'tsmom_28d_short_flat_reversal_1d')) {
+        throw new Wave9PaperAdmissionGuardError('candidateId does not name a frozen Wave 9 leg');
+    }
+    if ((direction === 'LONG' ? 'BUY' : 'SELL') !== decision.side) {
+        throw new Wave9PaperAdmissionGuardError('entry side does not match candidate direction');
+    }
+    return { eventTime, direction: direction };
+}
+/**
+ * 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 function captureWave9PaperAccountSnapshot(adapter) {
+    if (adapter.isLive) {
+        throw new Wave9PaperAdmissionGuardError('Wave 9 paper account capture hard-refuses a live adapter');
+    }
+    const simulator = adapter.getSimulator?.();
+    if (!simulator) {
+        throw new Wave9PaperAdmissionGuardError('Wave 9 account fingerprint requires a local paper simulator');
+    }
+    const state = simulator.getState();
+    const quoteCurrency = state.config.quoteCurrency;
+    const positions = state.positions.map((position) => {
+        const markPrice = simulator.getLastTicker(position.symbol)?.last ?? position.entryPrice;
+        const stopPrice = finiteOrNull(position.metadata?.originalStopPrice ?? position.metadata?.stopPrice);
+        return {
+            symbol: position.symbol,
+            side: position.side,
+            quantity: position.quantity,
+            entryPrice: position.entryPrice,
+            markPrice,
+            openedAt: position.openedAt,
+            missionId: position.metadata?.missionId ?? null,
+            setupType: position.metadata?.setupType ?? null,
+            candidateId: position.metadata?.candidateId ?? null,
+            strategy: position.metadata?.strategy ?? null,
+            accruedFundingUsd: finiteOrNull(position.metadata?.accruedFundingUsd),
+            fundingThroughTime: position.metadata?.fundingThroughTime ?? null,
+            stopPrice,
+            initialOpenRiskUsd: stopPrice === null
+                ? null
+                : Math.abs(position.entryPrice - stopPrice) * position.quantity,
+        };
+    }).sort((left, right) => left.symbol.localeCompare(right.symbol)
+        || left.side.localeCompare(right.side)
+        || left.openedAt.localeCompare(right.openedAt));
+    const openOrders = state.openOrders.map((order) => ({
+        id: order.id,
+        symbol: order.symbol,
+        side: order.side,
+        type: order.type,
+        amount: order.amount,
+        filled: order.filled,
+        price: finiteOrNull(order.price),
+    })).sort((left, right) => left.id.localeCompare(right.id));
+    const snapshot = {
+        schema: 'wave9-paper-account-v1',
+        savedAt: finiteOrNull(state.savedAt),
+        quoteCurrency,
+        wallet: Object.entries(state.wallet).map(([currency, balance]) => ({
+            currency,
+            total: balance.total,
+            available: balance.available,
+            locked: balance.locked,
+        })).sort((left, right) => left.currency.localeCompare(right.currency)),
+        equityUsd: simulator.computeEquity(),
+        sessionStartNavUsd: finiteOrNull(state.sessionStartNav),
+        positions,
+        openOrders,
+        closedWave9CandidateIds: [...new Set(state.tradeHistory
+                .filter((trade) => isWave9ManagedPosition(trade.metadata ?? {}))
+                .map((trade) => trade.metadata?.candidateId)
+                .filter((candidateId) => typeof candidateId === 'string' && candidateId.length > 0))]
+            .sort((left, right) => left.localeCompare(right)),
+    };
+    const fingerprint = createHash('sha256').update(JSON.stringify(snapshot)).digest('hex');
+    return {
+        fingerprint,
+        snapshot,
+        authoritative: false,
+        runtimeParity: false,
+        provenance: 'process_local_unlocked_simulator',
+    };
+}
+/** Stable held-position identity for a mechanical reversal close. */
+export function captureWave9PaperPositionFingerprint(adapter, symbol) {
+    const account = captureWave9PaperAccountSnapshot(adapter);
+    const canonical = canonicalSymbol(symbol);
+    const matches = account.snapshot.positions.filter((position) => canonicalSymbol(position.symbol) === canonical);
+    if (matches.length !== 1) {
+        throw new Wave9PaperAdmissionGuardError(`Wave 9 exit fingerprint requires exactly one held ${canonical} position`);
+    }
+    const row = matches[0];
+    const snapshot = {
+        symbol: row.symbol,
+        side: row.side,
+        quantity: row.quantity,
+        entryPrice: row.entryPrice,
+        openedAt: row.openedAt,
+        missionId: row.missionId,
+        setupType: row.setupType,
+        candidateId: row.candidateId,
+        strategy: row.strategy,
+        stopPrice: row.stopPrice,
+        initialOpenRiskUsd: row.initialOpenRiskUsd,
+    };
+    return {
+        fingerprint: createHash('sha256').update(JSON.stringify(snapshot)).digest('hex'),
+        snapshot,
+        authoritative: false,
+        runtimeParity: false,
+        provenance: 'process_local_unlocked_simulator',
+    };
+}
+/** In-memory capability guard shared by get_wave9_status and mutation tools. */
+export class Wave9PaperAdmissionGuard {
+    now;
+    tokenTtlMs;
+    batches = new Map();
+    events = new Map();
+    entriesByToken = new Map();
+    exitsByIdentity = new Map();
+    exitsByToken = new Map();
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.tokenTtlMs = options.tokenTtlMs ?? 120_000;
+        if (!Number.isFinite(this.tokenTtlMs) || this.tokenTtlMs <= 0 || this.tokenTtlMs > 10 * 60_000) {
+            throw new Wave9PaperAdmissionGuardError('tokenTtlMs must be in (0, 600000]');
+        }
+    }
+    issueBatch(decisions) {
+        if (decisions.length === 0)
+            throw new Wave9PaperAdmissionGuardError('cannot issue an empty admission batch');
+        if (decisions.length !== 1) {
+            throw new Wave9PaperAdmissionGuardError('only the next accepted Wave 9 candidate may be authorized; re-evaluate the actual book after its fill');
+        }
+        const sorted = decisions.map((decision) => ({ ...decision })).sort((a, b) => a.sequence - b.sequence);
+        const first = sorted[0];
+        exactText(first.batchId, 'batchId');
+        requireExecutionMode(first.tradingMode);
+        if (!FINGERPRINT_PATTERN.test(first.accountFingerprint)) {
+            throw new Wave9PaperAdmissionGuardError('accountFingerprint is malformed');
+        }
+        let eventTime = '';
+        const identities = new Set();
+        for (const decision of sorted) {
+            if (!Number.isInteger(decision.sequence) || decision.sequence < 0) {
+                throw new Wave9PaperAdmissionGuardError('entry sequence must be a non-negative integer');
+            }
+            requireExecutionMode(decision.tradingMode);
+            if (decision.batchId !== first.batchId
+                || decision.accountFingerprint !== first.accountFingerprint
+                || decision.tradingMode !== first.tradingMode) {
+                throw new Wave9PaperAdmissionGuardError('one batch must share batchId, accountFingerprint, and tradingMode');
+            }
+            exactText(decision.candidateId, 'candidateId');
+            exactText(decision.missionId, 'missionId');
+            if (identities.has(decision.candidateId))
+                throw new Wave9PaperAdmissionGuardError('duplicate candidateId');
+            identities.add(decision.candidateId);
+            if (!WAVE9_SYMBOL_PRIORITY.includes(decision.symbol)) {
+                throw new Wave9PaperAdmissionGuardError(`unsupported Wave 9 symbol ${decision.symbol}`);
+            }
+            const parsed = parseEntryCandidate(decision);
+            if (eventTime && parsed.eventTime !== eventTime) {
+                throw new Wave9PaperAdmissionGuardError('one admission batch must share an eventTime');
+            }
+            eventTime = parsed.eventTime;
+            if (decision.missionId !== stableMissionId(decision.candidateId)) {
+                throw new Wave9PaperAdmissionGuardError('missionId does not match stable candidate identity');
+            }
+            exactPositiveNumber(decision.quantity, 'quantity');
+            exactPositiveNumber(decision.stopPrice, 'stopPrice');
+            this.validateWindow(decision.notBeforeMs, decision.deadlineMs);
+        }
+        const event = this.events.get(eventTime) ?? { consumedCandidateIds: new Set() };
+        this.events.set(eventTime, event);
+        if (event.latchedReason || event.inFlightCandidateId)
+            return [];
+        if (event.consumedCandidateIds.has(first.candidateId))
+            return [];
+        let batch = this.batches.get(first.batchId);
+        if (!batch) {
+            // Invalidate every untouched capability for this event before binding a
+            // newly evaluated fingerprint. Only one current mutation capability may
+            // exist even when status uses fingerprinted batch IDs.
+            for (const prior of this.batches.values()) {
+                if (prior.eventTime !== eventTime)
+                    continue;
+                for (const record of prior.records) {
+                    if (record.status !== 'issued')
+                        continue;
+                    this.entriesByToken.delete(record.token);
+                    record.status = 'consumed';
+                    record.retryableAfterAbort = false;
+                }
+            }
+            batch = {
+                batchId: first.batchId,
+                accountFingerprint: first.accountFingerprint,
+                eventTime,
+                nextSequence: first.sequence,
+                records: sorted.map((decision) => this.newEntryRecord(decision)),
+            };
+            this.batches.set(first.batchId, batch);
+            for (const record of batch.records)
+                this.entriesByToken.set(record.token, record);
+        }
+        else {
+            const old = batch.records[0];
+            const same = batch.eventTime === eventTime
+                && batch.accountFingerprint === first.accountFingerprint
+                && this.sameEntryDecision(old, first);
+            if (same && old.status === 'consumed' && old.retryableAfterAbort) {
+                this.entriesByToken.delete(old.token);
+                batch = {
+                    batchId: first.batchId,
+                    accountFingerprint: first.accountFingerprint,
+                    eventTime,
+                    nextSequence: first.sequence,
+                    records: [this.newEntryRecord(first)],
+                };
+                this.batches.set(first.batchId, batch);
+                this.entriesByToken.set(batch.records[0].token, batch.records[0]);
+            }
+            else if (!same) {
+                if (old.status === 'in_flight') {
+                    throw new Wave9PaperAdmissionGuardError('cannot replace an in-flight Wave 9 admission');
+                }
+                if (old.status === 'consumed'
+                    && !old.retryableAfterAbort
+                    && !event.consumedCandidateIds.has(old.candidateId)) {
+                    throw new Wave9PaperAdmissionGuardError('cannot replace an attempted Wave 9 admission');
+                }
+                this.entriesByToken.delete(old.token);
+                batch = {
+                    batchId: first.batchId,
+                    accountFingerprint: first.accountFingerprint,
+                    eventTime,
+                    nextSequence: first.sequence,
+                    records: [this.newEntryRecord(first)],
+                };
+                this.batches.set(first.batchId, batch);
+                this.entriesByToken.set(batch.records[0].token, batch.records[0]);
+            }
+        }
+        if (batch.latchedReason)
+            return [];
+        const now = this.now();
+        const issued = [];
+        for (const record of batch.records) {
+            if (record.status === 'consumed' || record.sequence < batch.nextSequence || record.deadlineMs <= now)
+                continue;
+            if (record.status === 'issued' && record.tokenDeadlineMs <= now)
+                this.rotateEntryToken(record);
+            if (record.status !== 'issued')
+                continue;
+            issued.push({
+                token: record.token,
+                batchId: record.batchId,
+                candidateId: record.candidateId,
+                missionId: record.missionId,
+                sequence: record.sequence,
+                deadlineMs: record.tokenDeadlineMs,
+                accountFingerprint: record.accountFingerprint,
+                tradingMode: record.tradingMode,
+            });
+        }
+        return issued;
+    }
+    issueExitBatch(decisions) {
+        if (decisions.length === 0)
+            throw new Wave9PaperAdmissionGuardError('cannot issue an empty exit batch');
+        const now = this.now();
+        const seen = new Set();
+        const issued = [];
+        for (const input of decisions) {
+            const decision = { ...input };
+            this.validateExitDecision(decision);
+            const identity = this.exitIdentity(decision);
+            if (seen.has(identity))
+                throw new Wave9PaperAdmissionGuardError('duplicate exit identity');
+            seen.add(identity);
+            let record = this.exitsByIdentity.get(identity);
+            if (record) {
+                // A reduce-only LIVE close can have an ambiguous response or leave a
+                // partial position. Once its in-flight lease is explicitly aborted as
+                // retryable, a fresh trusted position snapshot must be able to issue a
+                // new authorization even though the residual fingerprint changed.
+                // Evaluate that terminal retry state before exact-decision replacement;
+                // otherwise the changed fingerprint is rejected as an attempted exit.
+                if (record.status === 'consumed' && record.retryableAfterAbort) {
+                    this.exitsByToken.delete(record.token);
+                    record = this.newExitRecord(decision);
+                    this.exitsByIdentity.set(identity, record);
+                    this.exitsByToken.set(record.token, record);
+                }
+                else {
+                    const same = this.sameExitDecision(record, decision);
+                    if (!same && record.status === 'issued') {
+                        this.exitsByToken.delete(record.token);
+                        record = this.newExitRecord(decision);
+                        this.exitsByIdentity.set(identity, record);
+                        this.exitsByToken.set(record.token, record);
+                    }
+                    else if (!same) {
+                        throw new Wave9PaperAdmissionGuardError('cannot replace an attempted Wave 9 exit authorization');
+                    }
+                    if (record.status === 'consumed')
+                        continue;
+                    if (record.status === 'issued' && record.tokenDeadlineMs <= now && record.deadlineMs > now) {
+                        this.rotateExitToken(record);
+                    }
+                }
+            }
+            else {
+                record = this.newExitRecord(decision);
+                this.exitsByIdentity.set(identity, record);
+                this.exitsByToken.set(record.token, record);
+            }
+            if (record.status === 'issued' && record.deadlineMs > now) {
+                issued.push({
+                    token: record.token,
+                    candidateId: record.candidateId,
+                    missionId: record.missionId,
+                    deadlineMs: record.tokenDeadlineMs,
+                    positionFingerprint: record.positionFingerprint,
+                    tradingMode: record.tradingMode,
+                });
+            }
+        }
+        return issued;
+    }
+    beginEntry(request) {
+        this.validateTokenShape(request.token, 'entry');
+        const record = this.entriesByToken.get(request.token);
+        if (!record || !sameSecret(record.token, request.token))
+            throw new Wave9PaperAdmissionGuardError('unknown Wave 9 admission token');
+        const batch = this.batches.get(record.batchId);
+        if (!batch)
+            throw new Wave9PaperAdmissionGuardError('Wave 9 admission batch is unavailable');
+        if (batch.latchedReason)
+            throw new Wave9PaperAdmissionGuardError(`Wave 9 admission batch is latched: ${batch.latchedReason}`);
+        this.assertUsable(record);
+        if (record.sequence !== batch.nextSequence) {
+            throw new Wave9PaperAdmissionGuardError(`Wave 9 admission sequence ${record.sequence} cannot run before ${batch.nextSequence}`);
+        }
+        const event = this.events.get(batch.eventTime);
+        if (!event || event.latchedReason || event.inFlightCandidateId) {
+            throw new Wave9PaperAdmissionGuardError('Wave 9 daily event is unavailable or already in flight');
+        }
+        if (request.setupType !== WAVE9_BUNDLE_SETUP_TYPE)
+            throw new Wave9PaperAdmissionGuardError('Wave 9 setup_type mismatch');
+        requireExecutionMode(request.tradingMode);
+        if (request.type.toLowerCase() !== 'market')
+            throw new Wave9PaperAdmissionGuardError('Wave 9 entries must use immediate market execution');
+        if (canonicalSymbol(request.symbol) !== record.symbol
+            || request.side.toUpperCase() !== record.side
+            || request.quantity !== exactPositiveNumber(record.quantity, 'quantity')
+            || request.stopPrice !== exactPositiveNumber(record.stopPrice, 'stopPrice')
+            || request.candidateId !== record.candidateId
+            || request.missionId !== record.missionId
+            || request.tradingMode !== record.tradingMode) {
+            throw new Wave9PaperAdmissionGuardError('Wave 9 order does not exactly match its frozen admission');
+        }
+        this.assertFingerprint(record.accountFingerprint, request.accountFingerprint);
+        event.inFlightCandidateId = record.candidateId;
+        return this.lease(record, 'entry');
+    }
+    beginExit(request) {
+        this.validateTokenShape(request.token, 'exit');
+        const record = this.exitsByToken.get(request.token);
+        if (!record || !sameSecret(record.token, request.token))
+            throw new Wave9PaperAdmissionGuardError('unknown Wave 9 exit token');
+        this.assertUsable(record);
+        requireExecutionMode(request.tradingMode);
+        if (!isWave9ManagedPosition({ setupType: request.setupType, missionId: request.missionId })
+            || request.reason !== WAVE9_MECHANICAL_EXIT_REASON
+            || canonicalSymbol(request.symbol) !== record.symbol
+            || request.positionSide !== record.positionSide
+            || request.candidateId !== record.candidateId
+            || request.missionId !== record.missionId
+            || request.tradingMode !== record.tradingMode) {
+            throw new Wave9PaperAdmissionGuardError('Wave 9 close does not exactly match its reversal authorization');
+        }
+        this.assertFingerprint(record.positionFingerprint, request.positionFingerprint);
+        return this.lease(record, 'exit');
+    }
+    revalidate(lease, fingerprint) {
+        const record = this.recordForLease(lease);
+        if (record.status !== 'in_flight' || record.leaseId !== lease.leaseId) {
+            throw new Wave9PaperAdmissionGuardError('Wave 9 authorization lease is no longer active');
+        }
+        if (this.now() >= record.tokenDeadlineMs || this.now() >= record.deadlineMs) {
+            throw new Wave9PaperAdmissionGuardError('Wave 9 authorization expired before mutation');
+        }
+        const expected = lease.kind === 'entry'
+            ? record.accountFingerprint
+            : record.positionFingerprint;
+        this.assertFingerprint(expected, fingerprint);
+    }
+    commit(lease) {
+        const record = this.recordForLease(lease);
+        if (record.status !== 'in_flight' || record.leaseId !== lease.leaseId) {
+            throw new Wave9PaperAdmissionGuardError('Wave 9 authorization lease is no longer active');
+        }
+        record.status = 'consumed';
+        record.leaseId = undefined;
+        if (lease.kind === 'entry') {
+            const entry = record;
+            const batch = this.batches.get(entry.batchId);
+            if (!batch || entry.sequence !== batch.nextSequence) {
+                throw new Wave9PaperAdmissionGuardError('Wave 9 entry committed outside its frozen sequence');
+            }
+            batch.nextSequence += 1;
+            const event = this.events.get(batch.eventTime);
+            if (event) {
+                event.inFlightCandidateId = undefined;
+                event.consumedCandidateIds.add(entry.candidateId);
+            }
+        }
+        else {
+            record.retryableAfterAbort = false;
+        }
+    }
+    /**
+     * 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, reason, options = {}) {
+        const record = this.recordForLease(lease);
+        if (record.status !== 'in_flight' || record.leaseId !== lease.leaseId)
+            return;
+        record.status = 'consumed';
+        record.leaseId = undefined;
+        if (lease.kind === 'entry') {
+            const entry = record;
+            entry.retryableAfterAbort = options.retryable === true;
+            const batch = this.batches.get(entry.batchId);
+            if (batch) {
+                const event = this.events.get(batch.eventTime);
+                if (event)
+                    event.inFlightCandidateId = undefined;
+                if (options.latchEvent !== false) {
+                    batch.latchedReason = reason.slice(0, 300);
+                    if (event) {
+                        event.latchedReason = batch.latchedReason;
+                    }
+                }
+            }
+        }
+        else {
+            record.retryableAfterAbort = options.retryable === true;
+        }
+    }
+    validateWindow(notBeforeMs, deadlineMs) {
+        requireFinite(notBeforeMs, 'notBeforeMs');
+        requireFinite(deadlineMs, 'deadlineMs');
+        if (!Number.isInteger(notBeforeMs) || !Number.isInteger(deadlineMs) || deadlineMs < notBeforeMs) {
+            throw new Wave9PaperAdmissionGuardError('authorization window is malformed');
+        }
+    }
+    newEntryRecord(decision) {
+        const token = this.newToken('entry');
+        return {
+            ...decision,
+            token,
+            tokenDeadlineMs: Math.min(decision.deadlineMs, this.now() + this.tokenTtlMs),
+            status: 'issued',
+            retryableAfterAbort: false,
+        };
+    }
+    newExitRecord(decision) {
+        const token = this.newToken('exit');
+        return {
+            ...decision,
+            token,
+            tokenDeadlineMs: Math.min(decision.deadlineMs, this.now() + this.tokenTtlMs),
+            status: 'issued',
+            retryableAfterAbort: false,
+        };
+    }
+    rotateEntryToken(record) {
+        this.entriesByToken.delete(record.token);
+        record.token = this.newToken('entry');
+        record.tokenDeadlineMs = Math.min(record.deadlineMs, this.now() + this.tokenTtlMs);
+        this.entriesByToken.set(record.token, record);
+    }
+    rotateExitToken(record) {
+        this.exitsByToken.delete(record.token);
+        record.token = this.newToken('exit');
+        record.tokenDeadlineMs = Math.min(record.deadlineMs, this.now() + this.tokenTtlMs);
+        this.exitsByToken.set(record.token, record);
+    }
+    newToken(kind) {
+        return `w9${kind === 'entry' ? 'e' : 'x'}_${randomBytes(32).toString('base64url')}`;
+    }
+    validateTokenShape(token, kind) {
+        if (typeof token !== 'string' || !TOKEN_PATTERN.test(token) || !token.startsWith(kind === 'entry' ? 'w9e_' : 'w9x_')) {
+            throw new Wave9PaperAdmissionGuardError(`malformed Wave 9 ${kind} token`);
+        }
+    }
+    assertUsable(record) {
+        const now = this.now();
+        if (record.status !== 'issued')
+            throw new Wave9PaperAdmissionGuardError('Wave 9 authorization token is already used');
+        if (now < record.notBeforeMs)
+            throw new Wave9PaperAdmissionGuardError('Wave 9 authorization is not active yet');
+        if (now >= record.tokenDeadlineMs || now >= record.deadlineMs)
+            throw new Wave9PaperAdmissionGuardError('Wave 9 authorization token expired');
+    }
+    lease(record, kind) {
+        const leaseId = randomBytes(24).toString('base64url');
+        record.status = 'in_flight';
+        record.leaseId = leaseId;
+        return Object.freeze({ leaseId, kind, token: record.token });
+    }
+    recordForLease(lease) {
+        const record = lease.kind === 'entry'
+            ? this.entriesByToken.get(lease.token)
+            : this.exitsByToken.get(lease.token);
+        if (!record || record.leaseId !== lease.leaseId) {
+            throw new Wave9PaperAdmissionGuardError('unknown Wave 9 authorization lease');
+        }
+        return record;
+    }
+    assertFingerprint(expected, actual) {
+        if (!FINGERPRINT_PATTERN.test(actual) || !sameSecret(expected, actual)) {
+            throw new Wave9PaperAdmissionGuardError('Wave 9 account changed after authorization; mutation refused');
+        }
+    }
+    sameEntryDecision(record, decision) {
+        return ['candidateId', 'missionId', 'symbol', 'side', 'quantity', 'stopPrice', 'sequence', 'notBeforeMs', 'deadlineMs', 'accountFingerprint', 'tradingMode']
+            .every((key) => record[key] === decision[key]);
+    }
+    validateExitDecision(decision) {
+        exactText(decision.candidateId, 'exit candidateId');
+        exactText(decision.missionId, 'missionId');
+        requireExecutionMode(decision.tradingMode);
+        if (decision.reason !== 'signal_reversal')
+            throw new Wave9PaperAdmissionGuardError('Wave 9 exit reason must be signal_reversal');
+        if (!WAVE9_SYMBOL_PRIORITY.includes(decision.symbol)) {
+            throw new Wave9PaperAdmissionGuardError(`unsupported Wave 9 symbol ${decision.symbol}`);
+        }
+        if (!['long', 'short'].includes(decision.positionSide))
+            throw new Wave9PaperAdmissionGuardError('positionSide is malformed');
+        if (decision.missionId !== stableMissionId(decision.candidateId)) {
+            throw new Wave9PaperAdmissionGuardError('exit missionId does not match stable candidate identity');
+        }
+        const parts = decision.candidateId.split('|');
+        const expectedStrategy = decision.positionSide === 'long'
+            ? 'tsmom_28d_long_flat_reversal_1d'
+            : 'tsmom_28d_short_flat_reversal_1d';
+        const expectedDirection = decision.positionSide === 'long' ? 'LONG' : 'SHORT';
+        if (parts.length !== 4
+            || parts[1] !== decision.symbol
+            || parts[2] !== expectedStrategy
+            || parts[3] !== expectedDirection) {
+            throw new Wave9PaperAdmissionGuardError('exit candidateId does not match held Wave 9 leg');
+        }
+        if (!FINGERPRINT_PATTERN.test(decision.positionFingerprint))
+            throw new Wave9PaperAdmissionGuardError('positionFingerprint is malformed');
+        this.validateWindow(decision.notBeforeMs, decision.deadlineMs);
+    }
+    exitIdentity(decision) {
+        return `${decision.candidateId}|${decision.missionId}|${decision.symbol}|${decision.positionSide}|${decision.tradingMode}`;
+    }
+    sameExitDecision(record, decision) {
+        return ['candidateId', 'missionId', 'symbol', 'positionSide', 'reason', 'notBeforeMs', 'deadlineMs', 'positionFingerprint', 'tradingMode']
+            .every((key) => record[key] === decision[key]);
+    }
+}