dexterm-cli 0.1.6 → 0.2.0

package/dist/packages/autotrade/src/desk-executor.js

@@ -0,0 +1,188 @@
+// dexterm autotrade — the paper-desk executor (task-1506 AT-4, AUTOTRADE-SPEC §5, §6.1). PAPER ONLY.
+//
+// Autotrade's orders through the app's existing paper desk (PaperExitDesk: the PaperAgentDesk plus exit plans)
+// instead of the backtest fill model, so the agent
+// path inherits every fence the desk already has: the armed mandate's caps at the agent tier (hands-free × 0.25),
+// the panic file, the control file, the keyless Jupiter quote with its bounded retry, and the hash-chained
+// journal. The strategy clamp has already sized the order; the desk's caps sit around it and both apply.
+//
+//   buy()   an entry or a ladder add. Refused unless the mandate is armed AND paper-only, and refused while the
+//           position monitor's heartbeat is stale (the monitor must be up to run the exits). Every entry fill
+//           registers its desk-side exit plan (P1), and carries a note (P4) naming the run, position and profile.
+//   sell()  a mechanical or agent exit, journaled by the desk as agent.paper.exit.<rule>.
+//   costRecoverySellUsd()  the proceeds curve a cost-recovery sell is sized on: a linear-impact estimate from one
+//           quote of the largest allowed slice, one confirming quote at the estimate, and at most one correction:
+//           never more than 3 quotes, inside the keyless budget.
+//   book()  the desk's book in USD, for `bankroll.source: desk`.
+//
+// Nothing here can sign, send or touch a key: the desk only accepts a paper executor, and this file imports
+// types only from the data layer (a refusal is recognised by its error name).
+export const DESK_EXIT_OWNER = 'autotrade-monitor';
+/** Most quotes a cost-recovery slice is sized on (the fill then takes its own fresh quote, as every desk fill does). */
+export const MAX_SIZING_QUOTES = 3;
+const errReason = (e) => (e instanceof Error && e.name === 'PaperDeskError' ? `desk-${e.reason}` : `desk-error:${e instanceof Error ? e.message.slice(0, 120) : String(e)}`);
+const r6 = (x) => Number(x.toPrecision(6));
+export class DeskExecutor {
+    name = 'paper-desk';
+    /** The monitor process owns the exits of every position this executor opens (a runner must not run them inline). */
+    exitsByMonitor = true;
+    d;
+    now;
+    seq = 0;
+    constructor(deps) {
+        this.d = deps;
+        this.now = deps.now ?? Date.now;
+    }
+    /** Why an entry may not go to the desk right now, or null. */
+    entryBlock() {
+        const m = this.d.mandate();
+        if (!m)
+            return 'no-mandate';
+        if (m.paperOnly !== true)
+            return 'mandate-not-paper-only';
+        if (m.status !== 'armed' || !m.armedBy)
+            return 'mandate-not-armed';
+        if (!this.d.monitorAlive())
+            return 'monitor-heartbeat-stale';
+        return null;
+    }
+    held(mint) {
+        return this.d.desk.positions().find((p) => p.mint === mint && p.tokens > 0) ?? null;
+    }
+    toFill(k, rec, reason) {
+        const solUsd = this.d.solUsd() ?? (rec.priceUsd && rec.priceSol ? rec.priceUsd / rec.priceSol : 0);
+        const usd = (Math.abs(Number(rec.solDelta)) / 1e9) * solUsd;
+        const tokens = Math.abs(Number(rec.tokenDelta)) / 10 ** rec.decimals;
+        return {
+            t: rec.t, side: rec.side, usd: r6(usd), tokens, price: k.price ?? (rec.priceSol * solUsd), avgPrice: tokens > 0 ? r6(usd / tokens) : 0,
+            impactPct: rec.priceImpactPct ?? 0, partial: false, reason,
+        };
+    }
+    /** An entry (or a ladder add) of `usd` through the desk, with its exit plan registered on the first fill. */
+    async buy(k, usd, ctx = {}) {
+        const block = this.entryBlock();
+        if (block)
+            return { refused: block };
+        const decimals = this.d.decimals(k.mint);
+        if (decimals === null)
+            return { refused: 'decimals-unknown' };
+        const kind = ctx.kind ?? (this.held(k.mint) ? 'add' : 'open');
+        const profile = ctx.profile ?? this.d.defaultProfile;
+        const positionId = ctx.positionId ?? `${this.d.runId ?? 'run'}:${k.mint.slice(0, 8)}:${this.now().toString(36)}${++this.seq}`;
+        const note = {
+            by: 'autotrade', kind, positionId, profile, runId: this.d.runId ?? null, sessionId: ctx.sessionId ?? null, mid: k.price,
+            ...(this.d.strategy ? { strategy: this.d.strategy.id, strategyHash: this.d.strategy.hash } : {}),
+            ...(ctx.reason ? { reason: ctx.reason.slice(0, 200) } : {}),
+        };
+        try {
+            const t = this.d.desk.open({ mint: k.mint, symbol: k.symbol, decimals, side: 'buy' });
+            this.d.desk.size(t.id, { usd });
+            const { fill } = await this.d.desk.confirm(t.id, { note });
+            if (kind === 'open')
+                this.d.desk.registerExitPlan({ mint: k.mint, owner: DESK_EXIT_OWNER, positionId, profileId: profile, runId: this.d.runId ?? null, note: { sessionId: ctx.sessionId ?? null } });
+            return this.toFill(k, fill, kind === 'open' ? 'entry' : 'ladder-add');
+        }
+        catch (e) {
+            return { refused: errReason(e) };
+        }
+    }
+    /** Sell `tokens` of the held position as exit rule `reason` (journaled agent.paper.exit.<reason>). */
+    async sell(k, tokens, reason, ctx = {}) {
+        const pos = this.held(k.mint);
+        if (!pos)
+            return { refused: 'no-position' };
+        const fraction = Math.min(1, tokens / pos.tokens);
+        if (!(fraction > 0))
+            return { refused: 'nothing-to-sell' };
+        try {
+            const r = await this.d.desk.exit({
+                mint: k.mint, fraction: fraction >= 0.999999 ? 1 : fraction, rule: reason, detail: ctx.detail,
+                note: { by: 'autotrade', runId: this.d.runId ?? null, ...(ctx.positionId ? { positionId: ctx.positionId } : {}), ...(ctx.agentReason ? { agentReason: ctx.agentReason.slice(0, 200) } : {}) },
+            });
+            return this.toFill(k, r.fill, reason);
+        }
+        catch (e) {
+            return { refused: errReason(e) };
+        }
+    }
+    /**
+     * The proceeds curve for a cost-recovery sell, from at most MAX_SIZING_QUOTES desk quotes (spec §9 AT-4):
+     *   1. quote the largest allowed slice (maxSellFrac of the bag): proceeds P at size C;
+     *   2. a linear-impact model through it (proceeds(t) = t·m·(1 − a·t), m = the tick's mid price) gives the
+     *      slice t* that nets the owed cost; quote t* to confirm;
+     *   3. if the confirmation is short, scale once (t3 = t*·owed/proceeds(t*), at most C) and quote that.
+     * Returns a monotone piecewise-linear `sellUsd(tokens)` through the quoted points for monitorTick's search, or
+     * null when no quote could be had (the monitor then waits for the next tick: a cost-recovery sell is never
+     * sized on a guess).
+     */
+    async costRecoverySellUsd(p, prof, k) {
+        const cr = prof.costRecovery;
+        const solUsd = this.d.solUsd();
+        if (!cr || !solUsd || !k.price || p.tokens <= 0)
+            return null;
+        const owed = p.costUsd - p.realizedUsd;
+        const cap = p.tokens * cr.maxSellFrac;
+        let quotes = 0;
+        const quote = async (tokens) => {
+            if (quotes >= MAX_SIZING_QUOTES)
+                return null;
+            quotes++;
+            try {
+                const q = await this.d.desk.previewSell({ mint: p.mint, fraction: Math.min(1, tokens / p.tokens) });
+                return q.solOut * solUsd;
+            }
+            catch {
+                return null;
+            }
+        };
+        const pts = [[0, 0]];
+        const pc = await quote(cap);
+        if (pc === null)
+            return null;
+        pts.push([cap, pc]);
+        if (owed > 0 && pc > owed) {
+            const m = k.price;
+            const a = Math.max(0, (1 - pc / (cap * m)) / cap);
+            // smaller root of a·m·t² − m·t + owed = 0 (or the no-impact line when a = 0)
+            const disc = m * m - 4 * a * m * owed;
+            const est = a > 0 && disc > 0 ? (m - Math.sqrt(disc)) / (2 * a * m) : owed / m;
+            const t1 = Math.min(cap, Math.max(cap * 1e-6, est));
+            const p1 = await quote(t1);
+            if (p1 !== null) {
+                pts.push([t1, p1]);
+                if (p1 < owed && p1 > 0) {
+                    const t2 = Math.min(cap, (t1 * owed) / p1);
+                    const p2 = t2 > t1 ? await quote(t2) : null;
+                    if (p2 !== null)
+                        pts.push([t2, p2]);
+                }
+            }
+        }
+        pts.sort((x, y) => x[0] - y[0]);
+        for (let i = 1; i < pts.length; i++)
+            pts[i][1] = Math.max(pts[i][1], pts[i - 1][1]); // monotone
+        const sellUsd = (t) => {
+            if (t <= 0)
+                return 0;
+            for (let i = 1; i < pts.length; i++) {
+                const [x0, y0] = pts[i - 1], [x1, y1] = pts[i];
+                if (t <= x1)
+                    return x1 === x0 ? y1 : y0 + ((y1 - y0) * (t - x0)) / (x1 - x0);
+            }
+            return pts[pts.length - 1][1];
+        };
+        return { sellUsd, quotes };
+    }
+    /** The desk's paper book in USD (for `bankroll.source: desk`): cash, open cost, and their sum. */
+    book() {
+        const solUsd = this.d.solUsd();
+        if (!solUsd)
+            return null;
+        const v = this.d.desk.pnl();
+        const cashUsd = v.balanceSol * solUsd;
+        const openCostUsd = v.openCostSol * solUsd;
+        return { paper: true, cashUsd: r6(cashUsd), openCostUsd: r6(openCostUsd), equityUsd: r6(cashUsd + openCostUsd), solUsd };
+    }
+    /** The desk's exit plans (read-only). */
+    exitPlans() { return this.d.desk.exitPlans(); }
+}

package/dist/packages/autotrade/src/engine.js

@@ -0,0 +1,401 @@
+// dexterm autotrade — the strategy engine (task-1498 spike, AUTOTRADE-SPEC §1, §4, §6).
+//
+// Pure, deterministic, no I/O. Three jobs:
+//   screen()     does this tick make the coin a candidate under the strategy's entry rules?
+//   clampEntry() turn an agent's (or the auto rule's) entry request into the size the strategy allows,
+//                with every reduction named. The agent can ask for anything; it gets at most this.
+//   SimBook      the paper book + the fill model shared by replays and backtests (constant-product impact
+//                on the recorded liquidity, fee, slippage, partial fills at the impact cap, unsellable exits).
+//
+// In a live paper run the fills come from the app's paper desk instead (real Jupiter quotes, the mandate
+// caps, the journal). The clamp is the first of
+// three independent fences, never the only one.
+import { parseFilter } from "../../cli/src/screener/filter.js";
+import { tickRow } from "./replay.js";
+export const DAY_MS = 86_400_000;
+const r2 = (x) => Math.round(x * 100) / 100;
+const r6 = (x) => Number(x.toPrecision(6));
+/** Compiled entry rules (the filter is parsed once per strategy). */
+export class EntryRules {
+    strategy;
+    predicate;
+    constructor(strategy) {
+        this.strategy = strategy;
+        const f = parseFilter(strategy.entry.screen);
+        if (!f.ok)
+            throw new Error(`entry.screen: ${f.error}`);
+        this.predicate = (k) => f.filter.predicate(tickRow(k));
+    }
+    screen(k) {
+        const e = this.strategy.entry;
+        const failed = [];
+        const matched = [];
+        if (k.kind !== 'live')
+            failed.push('not-listed');
+        if (k.price === null || k.price <= 0)
+            failed.push('no-price');
+        if (!this.predicate(k))
+            failed.push('screen');
+        const ageH = k.createdAt ? (k.t - k.createdAt) / 3600e3 : null;
+        if (ageH === null)
+            failed.push('age-unknown');
+        else if (ageH < e.ageHours.min || (e.ageHours.max !== null && ageH > e.ageHours.max))
+            failed.push('age');
+        const s = e.safety;
+        if (s.requireNoMintAuthority && k.mintAuth !== false)
+            failed.push(k.mintAuth === null ? 'mint-authority-unknown' : 'mint-authority');
+        if (s.requireNoFreezeAuthority && k.freezeAuth !== false)
+            failed.push(k.freezeAuth === null ? 'freeze-authority-unknown' : 'freeze-authority');
+        if (s.maxTop10Pct !== null) {
+            if (k.top10 === null) {
+                if (s.unknownHolders === 'reject')
+                    failed.push('holders-unknown');
+            }
+            else if (k.top10 > s.maxTop10Pct)
+                failed.push('top10');
+        }
+        if (s.maxDevPct !== null && k.dev !== null && k.dev > s.maxDevPct)
+            failed.push('dev-share');
+        if (s.maxMcapSplitX !== null && (k.mcapFlagged || splitX(k) > s.maxMcapSplitX))
+            failed.push('mcap-split');
+        if (s.youngVertical && ageH !== null && ageH < s.youngVertical.maxAgeHours && (k.chg1h ?? 0) >= s.youngVertical.maxH1Pct)
+            failed.push('young-vertical');
+        const fired = e.triggers.map((t) => {
+            switch (t.kind) {
+                case 'screen': return true;
+                case 'momentum': return (k.chg5m ?? -Infinity) >= t.m5MinPct && ratio(k.buys5m, k.sells5m) >= t.buySellMin;
+                // Live feeds only: a replay has no narrative heat or followed-wallet stream, so these never fire here.
+                case 'narrative': return false;
+                case 'wallet': return false;
+            }
+        });
+        e.triggers.forEach((t, i) => { if (fired[i])
+            matched.push(`trigger:${t.kind}`); });
+        const trig = e.triggerMode === 'all' ? fired.every(Boolean) : fired.some(Boolean);
+        if (!trig)
+            failed.push('trigger');
+        return { pass: failed.length === 0, matched, failed };
+    }
+}
+export function splitX(k) {
+    if (!k.mcap || !k.mcapResolved)
+        return 1;
+    return Math.max(k.mcap, k.mcapResolved) / Math.max(1e-9, Math.min(k.mcap, k.mcapResolved));
+}
+const ratio = (a, b) => (a === null || b === null ? 0 : b === 0 ? (a > 0 ? Infinity : 0) : a / b);
+/** Buy `usd` against the recorded pool. Constant product on half the liquidity; a partial fill at the impact cap. */
+export function simBuy(k, usd, x) {
+    if (!k.price || k.price <= 0)
+        return { refused: 'no-price' };
+    if (!k.liq || k.liq <= 0)
+        return { refused: 'no-liquidity' };
+    const R = k.liq / 2;
+    const net = usd - x.networkFeeUsd;
+    if (net <= 0)
+        return { refused: 'below-network-fee' };
+    let input = net * (1 - x.feeBps / 1e4);
+    // Constant product: the average price paid is mid × (1 + input / R), so the impact is input / R.
+    const capIn = R * (x.maxPriceImpactPct / 100);
+    const partial = input > capIn;
+    if (partial)
+        input = capIn;
+    const tokens = ((R / k.price) * input) / (R + input) / (1 + x.slippageBps / 1e4);
+    const spent = partial ? input / (1 - x.feeBps / 1e4) + x.networkFeeUsd : usd;
+    return { t: k.t, side: 'buy', usd: r6(spent), tokens, price: k.price, avgPrice: r6(spent / tokens), impactPct: r2((input / R) * 100), partial, reason: 'entry' };
+}
+/** Sell `tokens` into the recorded pool. Below minExitLiquidityUsd (or no pool) nothing sells: the bag is stuck. */
+export function simSell(k, tokens, x, reason) {
+    if (!k.price || k.price <= 0)
+        return { refused: 'no-price' };
+    if (!k.liq || k.liq < x.minExitLiquidityUsd)
+        return { refused: 'illiquid' };
+    const R = k.liq / 2;
+    const V = tokens * k.price;
+    const gross = (V * R) / (R + V);
+    const usd = gross * (1 - x.feeBps / 1e4) * (1 - x.slippageBps / 1e4) - x.networkFeeUsd;
+    if (usd <= 0)
+        return { refused: 'dust' };
+    return { t: k.t, side: 'sell', usd: r6(usd), tokens, price: k.price, avgPrice: r6(usd / tokens), impactPct: r2((V / (R + V)) * 100), partial: false, reason };
+}
+/** Value of a position if sold now through the same model (0 when it cannot be sold). */
+export function liquidationValue(p, k, x) {
+    if (p.tokens <= 0)
+        return 0;
+    const f = simSell(k, p.tokens, x, 'mark');
+    return 'refused' in f ? 0 : f.usd;
+}
+export class SimBook {
+    strategy;
+    state;
+    open = new Map();
+    closed = [];
+    seq = 0;
+    triggers = new Map();
+    /** The shared paper account this book trades from (task-1538), or null: the book owns its bankroll. */
+    account;
+    constructor(strategy, now, account, member) {
+        this.strategy = strategy;
+        this.account = account ?? null;
+        const start = account ? account.bookEquity() : strategy.bankroll.startUsd;
+        this.state = { cashUsd: start, peakEquityUsd: start, dayStart: dayOf(now), dayStartEquityUsd: start, dayRealizedUsd: 0, entriesToday: 0, lossStreak: 0, cooldownUntil: 0, halted: null, sizeDown: false, perCoin: {} };
+        if (account) {
+            // On a shared account the cash IS the account's: every fill and sale below moves the wallet's cash.
+            Object.defineProperty(this.state, 'cashUsd', { get: () => account.cashUsd, set: (v) => { account.cashUsd = v; }, enumerable: true });
+            account.join(this, member);
+        }
+    }
+    /** Book equity: cash + the cost basis still open (unrealized gains do not count for sizing). On an account: the account's. */
+    bookEquity() {
+        if (this.account)
+            return this.account.bookEquity();
+        let e = this.state.cashUsd;
+        for (const p of this.open.values())
+            e += Math.max(0, p.costUsd - p.realizedUsd);
+        return e;
+    }
+    /** Marked equity: cash + what every open bag would sell for now (stuck bags count 0). On an account: the account's. */
+    markedEquity() {
+        if (this.account)
+            return this.account.markedEquity();
+        let e = this.state.cashUsd;
+        for (const p of this.open.values())
+            e += liquidationValue(p, p.lastTick, this.strategy.execution);
+        return e;
+    }
+    /** This book's own open cost basis (its exposure, also on a shared account). */
+    exposureUsd() { return this.openCostUsd(); }
+    openCostUsd() {
+        let e = 0;
+        for (const p of this.open.values())
+            e += Math.max(0, p.costUsd - p.realizedUsd);
+        return e;
+    }
+    /** What this book's open bags would sell for now. */
+    openMarkUsd() {
+        let e = 0;
+        for (const p of this.open.values())
+            e += liquidationValue(p, p.lastTick, this.strategy.execution);
+        return e;
+    }
+    /** This book's own P/L: closed trades + the open bags marked now (on a shared account, the strategy's share). */
+    ownPnlUsd() {
+        let e = 0;
+        for (const t of this.closed)
+            e += t.pnlUsd;
+        for (const p of this.open.values())
+            e += liquidationValue(p, p.lastTick, this.strategy.execution) + p.realizedUsd - p.costUsd;
+        return e;
+    }
+    /** Day roll, drawdown size-down / halt. Called by the runner on every step. */
+    roll(now) {
+        const s = this.state;
+        const d = dayOf(now);
+        if (d !== s.dayStart) {
+            s.dayStart = d;
+            s.dayRealizedUsd = 0;
+            s.entriesToday = 0;
+            s.dayStartEquityUsd = this.bookEquity();
+            if (s.halted === 'daily-loss')
+                s.halted = null;
+        }
+        const eq = this.markedEquity();
+        s.peakEquityUsd = Math.max(s.peakEquityUsd, eq);
+        const dd = ((s.peakEquityUsd - eq) / s.peakEquityUsd) * 100;
+        const r = this.strategy.risk.drawdown;
+        if (dd >= r.haltAtPct && !s.halted)
+            s.halted = 'drawdown';
+        if (dd >= r.sizeDownAtPct)
+            s.sizeDown = true;
+        else if (dd < r.recoverBelowPct)
+            s.sizeDown = false;
+    }
+    openPosition(k, fill, profile, sessionId, trigger, ladder) {
+        const id = `p${++this.seq}`;
+        const p = {
+            id, mint: k.mint, symbol: k.symbol, profileId: profile.id, openedAt: k.t, sessionId,
+            tokens: fill.tokens, origTokens: fill.tokens, costUsd: fill.usd, realizedUsd: 0, entryPrice: fill.price, peakPrice: fill.price, troughPrice: fill.price,
+            tpFilled: 0, trailArmed: false, ladder, fills: [fill], status: 'open', stuck: false, closedAt: null, exitReason: null,
+            liqWindow: [{ t: k.t, liq: k.liq ?? 0 }], lowTapeSince: null, lastTick: k, wakeSent: {},
+        };
+        this.state.cashUsd -= fill.usd;
+        this.state.entriesToday++;
+        const c = (this.state.perCoin[k.mint] ??= { entries: 0, lastExit: 0 });
+        c.entries++;
+        this.open.set(k.mint, p);
+        this.triggers.set(id, trigger);
+        return p;
+    }
+    /**
+     * 0.2.0 card B (service-recover.ts): take over a position a crashed run left open. Its open cost leaves this
+     * book's cash (it is exposure here now); the coin counts as entered, so the per-coin rules see it.
+     */
+    adopt(p) {
+        if (this.open.has(p.mint))
+            return false;
+        this.state.cashUsd -= Math.max(0, p.costUsd - p.realizedUsd);
+        (this.state.perCoin[p.mint] ??= { entries: 0, lastExit: 0 }).entries++;
+        this.open.set(p.mint, p);
+        this.triggers.set(p.id, ['resumed']);
+        return true;
+    }
+    addTranche(p, fill) {
+        this.state.cashUsd -= fill.usd;
+        const tokens = p.tokens + fill.tokens;
+        p.entryPrice = (p.entryPrice * p.tokens + fill.price * fill.tokens) / tokens;
+        p.tokens = tokens;
+        p.origTokens += fill.tokens;
+        p.costUsd += fill.usd;
+        p.fills.push(fill);
+    }
+    /** Book a sell; closes the position when nothing is left. */
+    sell(p, fill) {
+        p.tokens = Math.max(0, p.tokens - fill.tokens);
+        if (p.tokens < p.origTokens * 1e-6)
+            p.tokens = 0;
+        p.realizedUsd += fill.usd;
+        this.state.cashUsd += fill.usd;
+        p.fills.push(fill);
+        if (p.tokens > 0)
+            return null;
+        return this.close(p, fill.t, fill.reason, false);
+    }
+    /** Close the books on a position (also used at the end of a run: stuck bags close at 0). */
+    close(p, t, reason, stuck) {
+        p.status = 'closed';
+        p.closedAt = t;
+        p.exitReason = reason;
+        p.stuck = stuck;
+        this.open.delete(p.mint);
+        const pnl = p.realizedUsd - p.costUsd;
+        const s = this.state;
+        s.dayRealizedUsd += pnl;
+        if (pnl < 0) {
+            s.lossStreak++;
+            if (s.lossStreak >= this.strategy.risk.lossStreak.losses) {
+                s.cooldownUntil = t + this.strategy.risk.lossStreak.cooldownMin * 60e3;
+                s.lossStreak = 0;
+            }
+        }
+        else
+            s.lossStreak = 0;
+        const lossPct = (-s.dayRealizedUsd / s.dayStartEquityUsd) * 100;
+        if (lossPct >= this.strategy.risk.dailyLossHaltPct && !s.halted)
+            s.halted = 'daily-loss';
+        (s.perCoin[p.mint] ??= { entries: 0, lastExit: 0 }).lastExit = t;
+        const ct = {
+            id: p.id, mint: p.mint, symbol: p.symbol, profileId: p.profileId, openedAt: p.openedAt, closedAt: t,
+            costUsd: r6(p.costUsd), proceedsUsd: r6(p.realizedUsd), pnlUsd: r6(pnl), pnlPct: r2((pnl / p.costUsd) * 100),
+            exitReason: reason, stuck, entryTrigger: this.triggers.get(p.id) ?? [], sessionId: p.sessionId, fills: p.fills,
+        };
+        this.closed.push(ct);
+        return ct;
+    }
+}
+export const dayOf = (t) => Math.floor(t / DAY_MS);
+/**
+ * The strategy's answer to "may I enter, and with how much?". Order: refusals (kill switch, halts,
+ * cooldowns, counts), then the size the strategy itself picks, then every ceiling, each reduction recorded.
+ * An agent request can only LOWER the size below the strategy's own pick, never raise it above a ceiling.
+ */
+export function clampEntry(book, k, req, killSwitch = false) {
+    const s = book.strategy;
+    const st = book.state;
+    const clamps = [];
+    const no = (refused) => ({ ok: false, refused, clamps });
+    // task-1571: paper only (dexterm holds no key and places no live order). task-1645: real is the same paper book; its
+    // fills become trade-fire signals for the user's own executor (the runner admits it only through the real-mode hook).
+    if (s.mode !== 'paper' && s.mode !== 'real')
+        return no('mode-not-paper');
+    if (killSwitch)
+        return no('kill-switch');
+    if (st.halted)
+        return no(`halted:${st.halted}`);
+    if (k.t < st.cooldownUntil)
+        return no('loss-streak-cooldown');
+    if (book.open.has(k.mint))
+        return no('already-open');
+    // Free bags (cost recovered) can stop counting as open positions, up to their own cap (exit profile 1.2.0).
+    const rb = s.risk.recoveredBags;
+    const bags = rb && !rb.countAsOpen ? [...book.open.values()].filter((p) => p.costRecovered).length : 0;
+    if (book.open.size - bags >= s.risk.maxConcurrent)
+        return no('max-concurrent');
+    if (rb && !rb.countAsOpen && book.open.size >= s.risk.maxConcurrent + rb.maxBags)
+        return no('max-open-with-bags');
+    if (st.entriesToday >= s.risk.maxEntriesPerDay)
+        return no('max-entries-per-day');
+    const coin = st.perCoin[k.mint];
+    const profileId = req.profile ?? s.exits.default;
+    const profile = s.exits.profiles[profileId];
+    if (!profile)
+        return no(`unknown-profile:${profileId}`);
+    if (coin) {
+        if (coin.entries >= s.risk.perCoin.maxEntries)
+            return no('per-coin-max-entries');
+        if (!profile.reentry.allowed)
+            return no('profile-no-reentry');
+        const cool = Math.max(s.risk.perCoin.cooldownMin, profile.reentry.cooldownMinutes) * 60e3;
+        if (k.t - coin.lastExit < cool)
+            return no('per-coin-cooldown');
+    }
+    if ((k.liq ?? 0) < profile.fit.minLiquidityUsd)
+        return no('profile-min-liquidity');
+    const bank = book.bookEquity();
+    const z = s.sizing;
+    let usd;
+    let basis;
+    switch (z.mode) {
+        case 'fixed':
+            usd = z.fixedUsd ?? 0;
+            basis = `fixed $${z.fixedUsd}`;
+            break;
+        case 'pct':
+            usd = (bank * (z.pct ?? 0)) / 100;
+            basis = `${z.pct}% of $${r2(bank)}`;
+            break;
+        case 'risk': {
+            const stop = profile.hardStop.enabled && profile.hardStop.atPct !== null ? Math.abs(profile.hardStop.atPct) : s.risk.perTrade.assumedLossPctNoStop;
+            usd = (bank * (z.riskPct ?? 0)) / stop;
+            basis = `${z.riskPct}% risk / ${stop}% stop of $${r2(bank)}`;
+            break;
+        }
+        case 'confidence': {
+            const c = z.confidence ?? { minPct: 1, maxPct: 1, default: 0.5 };
+            const conf = clamp01(req.confidence ?? c.default);
+            const pct = c.minPct + (c.maxPct - c.minPct) * conf;
+            usd = (bank * pct) / 100;
+            basis = `confidence ${r2(conf)} → ${r2(pct)}% of $${r2(bank)}`;
+            break;
+        }
+    }
+    // The agent may ask for LESS than the strategy's pick (never more).
+    const asked = req.sizeUsd ?? (req.sizePct !== undefined ? (bank * req.sizePct) / 100 : undefined);
+    if (asked !== undefined && Number.isFinite(asked)) {
+        if (asked < usd) {
+            basis += `, agent asked $${r2(asked)}`;
+            usd = Math.max(0, asked);
+        }
+        else if (asked > usd)
+            clamps.push({ rule: 'strategy-size', fromUsd: r2(asked), toUsd: r2(usd) });
+    }
+    const cap = (rule, limit) => { if (usd > limit + 1e-9) {
+        clamps.push({ rule, fromUsd: r2(usd), toUsd: r2(Math.max(0, limit)) });
+        usd = Math.max(0, limit);
+    } };
+    if (st.sizeDown)
+        cap('drawdown-size-down', usd * s.risk.drawdown.sizeDownMult);
+    cap('strategy-max-pct', (bank * s.sizing.maxPctOfBankroll) / 100);
+    cap('profile-max-pct', (bank * profile.sizing.maxSizePctOfBankroll) / 100);
+    cap('strategy-max-usd', s.sizing.maxUsd);
+    const lossPct = profile.hardStop.enabled && profile.hardStop.atPct !== null ? Math.abs(profile.hardStop.atPct) : s.risk.perTrade.assumedLossPctNoStop;
+    cap('per-trade-max-loss', (bank * s.risk.perTrade.maxLossPctOfBankroll) / lossPct);
+    cap('max-exposure', (bank * s.risk.maxExposurePct) / 100 - book.exposureUsd());
+    cap('cash', st.cashUsd);
+    const R = (k.liq ?? 0) / 2;
+    const imp = s.execution.maxPriceImpactPct / 100;
+    cap('price-impact', (R * imp) / (1 - s.execution.feeBps / 1e4) + s.execution.networkFeeUsd);
+    if (usd < s.sizing.minUsd)
+        return no(clamps.length ? `below-min-after-${clamps[clamps.length - 1].rule}` : 'below-min-size');
+    const first = z.ladder ? usd * z.ladder[0].frac : usd;
+    return { ok: true, usd: r2(usd), firstTrancheUsd: r2(first), profile, clamps, basis };
+}
+const clamp01 = (x) => (Number.isFinite(x) ? Math.min(1, Math.max(0, x)) : 0.5);