dexterm-cli 0.2.1 → 0.2.2

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

@@ -12,6 +12,7 @@
 // three independent fences, never the only one.
 import { parseFilter } from "../../cli/src/screener/filter.js";
 import { tickRow } from "./replay.js";
+import { TIERS_HARD_CAP_PCT, selectConfidenceTier, tierTable } from "./tiers.js";
 export const DAY_MS = 86_400_000;
 const r2 = (x) => Math.round(x * 100) / 100;
 const r6 = (x) => Number(x.toPrecision(6));
@@ -297,7 +298,7 @@ export const dayOf = (t) => Math.floor(t / DAY_MS);
  * 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) {
+export function clampEntry(book, k, req, killSwitch = false, nowMs = k.t, inFlight) {
     const s = book.strategy;
     const st = book.state;
     const clamps = [];
@@ -306,6 +307,11 @@ export function clampEntry(book, k, req, killSwitch = false) {
     // 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');
+    // 0.2.2: EXPERIMENTAL confidence tiers are PAPER ONLY. validateStrategy and the runner refuse them too; this is the
+    // engine's own fence for any document that reached it another way.
+    const tiersOn = s.sizing.tiers ?? null;
+    if (tiersOn && s.mode !== 'paper')
+        return no('tiers-paper-only');
     if (killSwitch)
         return no('kill-switch');
     if (st.halted)
@@ -339,34 +345,57 @@ export function clampEntry(book, k, req, killSwitch = false) {
     }
     if ((k.liq ?? 0) < profile.fit.minLiquidityUsd)
         return no('profile-min-liquidity');
+    // 0.2.2 confidence tiers: score the tick (fresh at nowMs), pick the tier; T0 is a skip; one open position unless the
+    // block says not. With tiers, an entry decided but not filled yet (the latency window, an open approval) counts as
+    // open for one-open and maxConcurrent, and its dollars come off the exposure and cash room (task-2156).
+    let tier;
+    const fly = tiersOn ? inFlightOf(inFlight) : { opens: 0, usd: 0 };
+    if (tiersOn) {
+        if (tiersOn.oneOpen !== false && book.open.size + fly.opens >= 1)
+            return no('tier-one-open');
+        if (book.open.size - bags + fly.opens >= s.risk.maxConcurrent)
+            return no('max-concurrent');
+        tier = selectConfidenceTier(k, tierTable(tiersOn.table), nowMs);
+        if (tier.tier === 'T0')
+            return { ok: false, refused: 'tier-T0', clamps, tier };
+    }
     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;
-        }
+    // With tiers on, the tier's runs-at % is the strategy's pick (an unproven tier above the cap is recorded as clamped
+    // from its configured size); every ceiling below still applies.
+    if (tier) {
+        usd = (bank * tier.effectivePct) / 100;
+        basis = `tier ${tier.tier} (score ${tier.score}/${tier.of}) ${tier.effectivePct}% of $${r2(bank)}`;
+        if (tier.capped)
+            clamps.push({ rule: 'tier-unproven-cap', fromUsd: r2((bank * tier.configuredPct) / 100), toUsd: r2(usd) });
     }
+    else
+        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)) {
@@ -381,6 +410,12 @@ export function clampEntry(book, k, req, killSwitch = false) {
         clamps.push({ rule, fromUsd: r2(usd), toUsd: r2(Math.max(0, limit)) });
         usd = Math.max(0, limit);
     } };
+    // The engine's own ceiling for a tiered entry, whatever the tier pick said: code, not the table or the strategy file.
+    if (tier) {
+        if (!Number.isFinite(usd))
+            usd = 0;
+        cap('tier-hard-cap', tierHardCapUsd(bank));
+    }
     if (st.sizeDown)
         cap('drawdown-size-down', usd * s.risk.drawdown.sizeDownMult);
     cap('strategy-max-pct', (bank * s.sizing.maxPctOfBankroll) / 100);
@@ -388,14 +423,25 @@ export function clampEntry(book, k, req, killSwitch = false) {
     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);
+    cap('max-exposure', (bank * s.risk.maxExposurePct) / 100 - book.exposureUsd() - fly.usd);
+    cap('cash', st.cashUsd - fly.usd);
     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');
+    if (usd < s.sizing.minUsd) {
+        const r = no(clamps.length ? `below-min-after-${clamps[clamps.length - 1].rule}` : 'below-min-size');
+        return tier ? { ...r, tier } : r;
+    }
     const first = z.ladder ? usd * z.ladder[0].frac : usd;
-    return { ok: true, usd: r2(usd), firstTrancheUsd: r2(first), profile, clamps, basis };
+    return { ok: true, usd: r2(usd), firstTrancheUsd: r2(first), profile, clamps, basis, ...(tier ? { tier } : {}) };
+}
+/** In-flight entries, failing closed: a negative or non-finite count is one open entry, such dollars are the whole room. */
+const inFlightOf = (f) => ({
+    opens: f === undefined ? 0 : Number.isFinite(f.opens) && f.opens >= 0 ? f.opens : 1,
+    usd: f === undefined ? 0 : Number.isFinite(f.usd) && f.usd >= 0 ? f.usd : Infinity,
+});
+/** The most a tiered position may cost in total (every tranche and add): TIERS_HARD_CAP_PCT of the book. */
+export function tierHardCapUsd(bookUsd) {
+    return Number.isFinite(bookUsd) && bookUsd > 0 ? (bookUsd * TIERS_HARD_CAP_PCT) / 100 : 0;
 }
 const clamp01 = (x) => (Number.isFinite(x) ? Math.min(1, Math.max(0, x)) : 0.5);

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

@@ -22,6 +22,7 @@
 // execution-port  where an approved entry goes: the paper port (local single-use proofs) and the live stub (task-1527)
 // chat       Telegram notify, control and approve-to-trade through the user's own bot; chat/ (task-1527)
 // yolo       task-1532: the full-port replay (rugs, loss spread, how often it zeroed the wallet); paper only
+// tiers      0.2.2: EXPERIMENTAL, UNPROVEN confidence-tiered sizing (sizing.tiers), PAPER ONLY, default off
 // signal / outbox / signal-channels / receipts / real-mode  task-1645: mode real = the paper engine + a LIVE TRADE FIRE
 //            signal per fill to the user's own executor (webhook, command hook, JSONL, MCP feed, Telegram copy); no key
 // limits / executor-health / report  task-1654: every real-mode limit user-set per scope (stricter wins), executor
@@ -57,6 +58,7 @@ export * from "./chat/index.js";
 export * from "./yolo.js";
 export * from "./rugproof.js";
 export * from "./rugproof-probe.js";
+export * from "./tiers.js";
 export * from "./signal.js";
 export * from "./outbox.js";
 export * from "./signal-channels.js";

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

@@ -21,12 +21,13 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, write
 import { uptime } from 'node:os';
 import { join } from 'node:path';
 import { Ledger, writeJsonAtomic } from "./ledger.js";
-import { EntryRules, SimBook, clampEntry, simBuy, simSell } from "./engine.js";
+import { EntryRules, SimBook, clampEntry, simBuy, tierHardCapUsd, simSell } from "./engine.js";
 import { monitorTick } from "./monitor.js";
 import { buildDelta, renderDelta, renderEvent, urgent, view } from "./session.js";
 import { SessionGate, renderDossierRecord, renderPositionDossier, tapeDossierRecord } from "./sessions.js";
 import { DEFAULT_RUNNER_CONFIG, effectiveCaps } from "./runner-config.js";
 import { DEFAULT_PRICE_BASIS, fillMcaps, levelText } from "./basis-text.js";
+import { confidenceTierLine, tierRecord } from "./tiers.js";
 export { Ledger } from "./ledger.js";
 export function simExecutor(x) {
     return { name: 'sim', buy: (k, usd) => simBuy(k, usd, x), sell: (k, tokens, reason) => simSell(k, tokens, x, reason) };
@@ -40,6 +41,10 @@ async function* fromArray(ticks) { for (const k of ticks)
     yield k; }
 export async function runAutotrade(o) {
     const s = o.strategy;
+    // 0.2.2: EXPERIMENTAL confidence tiers run on paper only: never in a real-signal run, never in any mode but paper
+    // (validateStrategy refuses the block outside paper and the engine refuses it too; this is the runner's own gate).
+    if (s.sizing.tiers && !(!o.real && s.mode === 'paper'))
+        throw new Error(`strategy ${s.id}: confidence tiers (sizing.tiers) are EXPERIMENTAL and PAPER ONLY: refused ${o.real ? 'in a real-signal run' : `in mode "${s.mode}"`} (remove sizing.tiers to run it there)`);
     // task-1571: autotrade runs on paper only. dexterm holds no key and places no live order; live trading happens in the
     // Telegram trading bot of the user's choice.
     // task-1645: mode "real" = the same paper engine, plus a LIVE TRADE FIRE signal per fill for the user's own executor;
@@ -78,6 +83,8 @@ export async function runAutotrade(o) {
     const skippedUntil = new Map();
     /** Coins the vet passed this run (a refused one goes to skippedUntil for good). */
     const vetted = new Set();
+    /** 0.2.2 confidence tiers: coins whose T0 (skip) line was already written at the pre-check. */
+    const tierSkipSaid = new Set();
     const orders = [];
     const refusals = {};
     const clampCount = {};
@@ -97,6 +104,24 @@ export async function runAutotrade(o) {
     const pumps = new Set();
     /** Proposals waiting for an answer, by mint (task-1527). */
     const approvalsOpen = new Map();
+    /** task-2156: the first-tranche dollars of each open approval (an in-flight entry for the tier clamp). */
+    const approvalUsd = new Map();
+    /** task-2156: entries decided but not filled (pending open orders + open approvals), other than `except`'s own. */
+    const inFlight = (except) => {
+        let opens = 0;
+        let usd = 0;
+        for (const q of orders)
+            if (q.kind === 'open' && q.mint !== except) {
+                opens++;
+                usd += q.usd;
+            }
+        for (const m of approvalsOpen.keys())
+            if (m !== except) {
+                opens++;
+                usd += approvalUsd.get(m) ?? Infinity;
+            }
+        return { opens, usd };
+    };
     ledger.add(t0, 'run_start', { strategy: s.id, version: s.version, strategyHash: s.hash, mode: s.mode, ...(o.real ? { tag: 'real-signal', accountId: o.real.accountId } : {}), ...(s.highRisk ? { highRisk: true } : {}), tape: o.tape?.source ?? o.source.name, ticks: tapeTicks?.length ?? null, decide: decideAuto ? 'auto' : s.entry.decide, ...(o.approvals ? { approvals: o.approvals.required(s) ? 'required' : 'when-asked' } : {}), pacing: pacing.mode, executor: exec.name, caps: capsView(gate), ...(o.account ? { account: o.account.id } : {}) });
     // task-1645 r2: a real run takes over the real positions an earlier run of this strategy left open (held.json),
     // so their exits keep firing. A profile the strategy no longer has falls back to its default profile.
@@ -312,8 +337,10 @@ export async function runAutotrade(o) {
                 return;
             }
             const req = { profile: d.profile, sizePct: d.sizePct, sizeUsd: d.sizeUsd, confidence: d.confidence };
-            const r = capYoungPool(clampEntry(book, k, req, killed), c);
-            ledger.add(now, 'clamp', { mint: c.mint, sessionId: c.session?.id ?? null, request: req, result: r.ok ? { ok: true, usd: r.usd, firstTrancheUsd: r.firstTrancheUsd, profile: r.profile.id, basis: r.basis, clamps: r.clamps } : r });
+            const r = capYoungPool(clampEntry(book, k, req, killed, now, inFlight(c.mint)), c);
+            ledger.add(now, 'clamp', { mint: c.mint, sessionId: c.session?.id ?? null, request: req, result: r.ok ? { ok: true, usd: r.usd, firstTrancheUsd: r.firstTrancheUsd, profile: r.profile.id, basis: r.basis, clamps: r.clamps } : r.tier ? { ok: false, refused: r.refused, clamps: r.clamps } : r, ...(r.tier ? { tier: tierRecord(r.tier) } : {}) });
+            if (r.tier)
+                say(confidenceTierLine(r.tier, k, r.ok ? r.usd : undefined));
             for (const cl of r.clamps)
                 clampCount[cl.rule] = (clampCount[cl.rule] ?? 0) + 1;
             if (!r.ok) {
@@ -398,7 +425,7 @@ export async function runAutotrade(o) {
                 const t = latest.get(c.mint);
                 if (!t)
                     return { ok: false, refused: 'no-tick' };
-                const rc = clampEntry(book, t, { profile: prof.id, sizeUsd: usd }, killed);
+                const rc = clampEntry(book, t, { profile: prof.id, sizeUsd: usd }, killed, now, inFlight(c.mint));
                 return rc.ok ? { ok: true, usd: rc.usd, clamps: rc.clamps.map((q) => q.rule) } : { ok: false, refused: rc.refused };
             },
             blocked: entryBlocked,
@@ -419,19 +446,32 @@ export async function runAutotrade(o) {
                     await closeCandidate(c, 'refused:approval-dropped');
                 return;
             }
-            const usd = Math.min(out.usd, r.usd);
-            const scale = r.usd > 0 ? usd / r.usd : 0;
             const t = latest.get(c.mint) ?? k;
+            let usd = Math.min(out.usd, r.usd);
+            // task-2156: a tiered entry re-clamps at the approval (one open, concurrency, room, a fresh tick), since other
+            // entries may have been decided or filled while it waited.
+            if (s.sizing.tiers) {
+                const rc = clampEntry(book, t, { profile: prof.id, sizeUsd: usd }, killed, now, inFlight(c.mint));
+                if (!rc.ok) {
+                    refuse('approval-dropped', { mint: c.mint, proposalId: out.proposalId, why: rc.refused });
+                    if (!c.closing)
+                        await closeCandidate(c, 'refused:approval-dropped');
+                    return;
+                }
+                usd = Math.min(usd, rc.usd);
+            }
+            const scale = r.usd > 0 ? usd / r.usd : 0;
             ledger.add(now, 'approval_granted', { mint: c.mint, proposalId: out.proposalId, via: out.via, usd, proofId: out.proofId ? `${out.proofId.slice(0, 6)}…` : null });
             say(`APPROVED ${k.symbol}: $${round2(usd)} via ${out.via}`);
             const ladder = (s.sizing.ladder ?? []).slice(1).map((tr) => ({ frac: tr.frac, atPct: tr.atPct, deadline: now + tr.withinMin * 60e3, usd: usd * tr.frac }));
             const first = round2(r.firstTrancheUsd * scale);
             orders.push({ mint: c.mint, fillAt: now + x.latencyMs, decidedPrice: t.price ?? 0, usd: first, firstUsd: first, profile: prof.id, sessionId: c.session?.id ?? null, trigger: c.matched, ladder, kind: 'open', ctx: { proofId: out.proofId, proposalId: out.proposalId, orderHash: out.orderHash } });
         };
+        approvalUsd.set(c.mint, r.firstTrancheUsd);
         const pending = o.approvals.request(prop, live)
             .catch((e) => ({ approved: false, state: 'ERROR', why: e instanceof Error ? e.message.slice(0, 120) : String(e) }))
             .then(settle)
-            .finally(() => { approvalsOpen.delete(c.mint); });
+            .finally(() => { approvalsOpen.delete(c.mint); approvalUsd.delete(c.mint); });
         approvalsOpen.set(c.mint, pending);
         // Lockstep (backtests, tests) waits for the answer; every other pacing lets it land when it lands.
         if (pacing.mode === 'lockstep')
@@ -531,11 +571,16 @@ export async function runAutotrade(o) {
             // Re-check at the fill, like a swap's slippage tolerance: a pool that drained or a price that ran
             // away between the decision and the fill refuses the order instead of buying into it.
             const prof0 = s.exits.profiles[q.profile];
-            const why = (k.liq ?? 0) < prof0.fit.minLiquidityUsd ? 'fill-liquidity-gone'
-                : k.price && q.decidedPrice && k.price > q.decidedPrice * (1 + x.slippageBps / 1e4) ? 'fill-slippage'
-                    // task-1538: on a shared paper account another strategy may have spent the cash since this order was decided;
-                    // the cash is held before the (async) fill so two strategies can never spend the same dollars.
-                    : book.account && !book.account.hold(q.usd) ? 'fill-account-cash' : null;
+            // task-2156: a tiered open re-checks one-open and concurrency at the fill (another entry may have filled first).
+            const tierBusy = s.sizing.tiers && q.kind === 'open'
+                ? (s.sizing.tiers.oneOpen !== false && book.open.size >= 1 ? 'fill-tier-one-open' : book.open.size >= s.risk.maxConcurrent ? 'fill-max-concurrent' : null)
+                : null;
+            const why = tierBusy ? tierBusy
+                : (k.liq ?? 0) < prof0.fit.minLiquidityUsd ? 'fill-liquidity-gone'
+                    : k.price && q.decidedPrice && k.price > q.decidedPrice * (1 + x.slippageBps / 1e4) ? 'fill-slippage'
+                        // task-1538: on a shared paper account another strategy may have spent the cash since this order was decided;
+                        // the cash is held before the (async) fill so two strategies can never spend the same dollars.
+                        : book.account && !book.account.hold(q.usd) ? 'fill-account-cash' : null;
             let f;
             try {
                 f = why ? { refused: why } : await exec.buy(k, q.usd, q.ctx);
@@ -763,7 +808,16 @@ export async function runAutotrade(o) {
                 else if (a.kind === 'add') {
                     if (killed || book.state.halted)
                         continue;
-                    const room = Math.min(a.usd, book.state.cashUsd, (book.bookEquity() * s.risk.maxExposurePct) / 100 - book.exposureUsd());
+                    let room = Math.min(a.usd, book.state.cashUsd, (book.bookEquity() * s.risk.maxExposurePct) / 100 - book.exposureUsd());
+                    // 0.2.2 confidence tiers: the whole position (every tranche) stays within the engine's tier ceiling (fails closed).
+                    if (s.sizing.tiers) {
+                        const left = tierHardCapUsd(book.bookEquity()) - pos.costUsd;
+                        if (!(left >= s.sizing.minUsd)) {
+                            refuse('ladder-add-tier-hard-cap', { positionId: pos.id });
+                            continue;
+                        }
+                        room = Number.isFinite(room) ? Math.min(room, left) : 0;
+                    }
                     if (room < s.sizing.minUsd) {
                         refuse('ladder-add-no-room', { positionId: pos.id });
                         continue;
@@ -807,11 +861,15 @@ export async function runAutotrade(o) {
                 const sr = rules.screen(k);
                 if (sr.pass) {
                     // Cheap pre-check so a full book does not spawn sessions it could never act on.
-                    const pre = clampEntry(book, k, {}, killed);
+                    const pre = clampEntry(book, k, {}, killed, now, inFlight(k.mint));
                     const v = pre.ok && o.vet && !vetted.has(k.mint) ? await vetCoin(k, vetCtx(k, pre.usd, h)) : null;
                     if (!pre.ok) {
                         if (!['already-open'].includes(pre.refused))
                             count(`precheck:${pre.refused}`);
+                        if (pre.tier?.tier === 'T0' && !tierSkipSaid.has(k.mint)) {
+                            tierSkipSaid.add(k.mint);
+                            say(confidenceTierLine(pre.tier, k));
+                        }
                     }
                     else if (v && !v.ok) {
                         // task-1748: a time gate (pool age, the second liquidity read) looks again later; any other refusal is for good.

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

@@ -81,7 +81,7 @@ export class StrategyStore {
                 return { id, source, ok: false, errors: r.errors, warnings: r.warnings };
             const s = r.strategy;
             return {
-                id, source, ok: true, name: s.name, version: s.version, hash: s.hash, mode: s.mode, ...(s.highRisk ? { highRisk: true } : {}), profiles: Object.keys(s.exits.profiles), warnings: r.warnings,
+                id, source, ok: true, name: s.name, version: s.version, hash: s.hash, mode: s.mode, ...(s.highRisk ? { highRisk: true } : {}), ...(s.sizing.tiers ? { experimentalTiers: true } : {}), profiles: Object.keys(s.exits.profiles), warnings: r.warnings,
                 ...(last[s.hash] ? { lastBacktest: last[s.hash] } : {}),
             };
         };

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

@@ -13,6 +13,7 @@ import { readFileSync, readdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { validate } from '../../custom/src/index.js';
 import { parseFilter } from "../../cli/src/screener/filter.js";
+import { TIER_TABLE_IDS, TIERS_VERDICT, tierTable, tierTableLines } from "./tiers.js";
 export const STRATEGY_SCHEMA = 'dexterm-strategy/1';
 export const EXIT_PROFILE_VERSION = '1.2.0';
 // ───────────────────────────── schema ─────────────────────────────
@@ -92,6 +93,7 @@ export const SCHEMAS = {
             confidence: obj({ minPct: num(0.1, 25), maxPct: num(0.1, 25), default: num(0, 1) }),
             ladder: { type: 'array', max: 4, items: obj({ frac: num(0.05, 1), atPct: num(-90, 1000), withinMin: num(1, 1440) }) },
             maxPctOfBankroll: num(0.1, 25), maxUsd: num(1, 1e6), minUsd: num(0.01, 1e6),
+            tiers: nullable(obj({ table: { type: 'string', enum: TIER_TABLE_IDS }, experimental: { type: 'string', enum: ['paper-only'] }, oneOpen: { type: 'boolean' } }, ['table', 'experimental'])),
         }, ['mode', 'maxPctOfBankroll', 'maxUsd', 'minUsd']),
         risk: obj({
             perTrade: obj({ maxLossPctOfBankroll: num(0.1, 25), assumedLossPctNoStop: num(10, 100) }),
@@ -209,6 +211,21 @@ export function validateStrategy(doc, library = builtinProfiles()) {
         errors.push({ path: '/risk/drawdown/recoverBelowPct', msg: 'recoverBelowPct must be below sizeDownAtPct' });
     if (s.execution.stuckWriteOffMin != null && s.mode !== 'paper')
         errors.push({ path: '/execution/stuckWriteOffMin', msg: `the stuck write-off is paper only: in mode ${s.mode} the bag is still in your wallet and keeps its exit signals (remove it or set it to null)` });
+    if (z.tiers) {
+        // 0.2.2: EXPERIMENTAL confidence tiers are PAPER ONLY (the runner and the engine refuse them outside paper too).
+        if (s.mode !== 'paper')
+            errors.push({ path: '/sizing/tiers', msg: `confidence tiers are EXPERIMENTAL and PAPER ONLY: refused in mode ${s.mode} (remove sizing.tiers or set it to null)` });
+        const tt = tierTable(z.tiers.table);
+        const rp = s.entry.safety.rugproof;
+        if (!rp || rp.minPoolAgeMin < tt.gates.minPoolAgeMin)
+            errors.push({ path: '/entry/safety/rugproof', msg: `confidence tiers need the rug-proof block with minPoolAgeMin ${tt.gates.minPoolAgeMin} or more (the pool age gate of table ${tt.id}; the tick alone cannot tell a pool's age)` });
+        warnings.push({ path: '/sizing/tiers', msg: TIERS_VERDICT });
+        for (const line of tierTableLines(tt).slice(1))
+            warnings.push({ path: '/sizing/tiers', msg: line });
+        warnings.push({ path: '/sizing/tiers', msg: `the tier's size replaces the size of sizing mode ${z.mode}; every limit still applies and the stricter wins (sizing.maxPctOfBankroll ${z.maxPctOfBankroll}%, maxUsd $${z.maxUsd}, the profile's max %, per-trade loss, exposure, cash, price impact, drawdown size-down)${z.tiers.oneOpen === false ? '' : '; one open position at a time'}; tier gates: liquidity >= $${tt.gates.minLiqUsd}, pool age >= ${tt.gates.minPoolAgeMin} min, not young and vertical` });
+        if (z.ladder)
+            warnings.push({ path: '/sizing/ladder', msg: 'with confidence tiers the ladder splits the tier size into tranches (the first fills at entry)' });
+    }
     if (s.agent.budgetUsdPerSession > s.agent.budgetUsdPerDay)
         errors.push({ path: '/agent/budgetUsdPerSession', msg: 'a session budget above the daily budget' });
     if (s.entry.ageHours.max !== null && s.entry.ageHours.max < s.entry.ageHours.min)

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

@@ -0,0 +1,194 @@
+// dexterm autotrade — confidence-tiered sizing, EXPERIMENTAL, UNPROVEN and PAPER ONLY (0.2.2, from the rules v4 research).
+//
+// A strategy opts in with `sizing.tiers` (strategy.ts). The ENGINE (clampEntry) then scores every candidate tick on
+// two measured points, maps the score to a tier and the tier to a size in % of the book. Nothing here reads the
+// agent's own confidence: the research found no held-out signal in it. The rules, all enforced in the engine:
+//   - T0 (score 0, or a failed tier gate) is a skip: no entry.
+//   - No tier runs above 25% of the book (TIERS_HARD_CAP_PCT). The cap is code: the table's evidence or cap fields,
+//     the strategy file and the agent cannot lift it, and the engine applies it again on the dollar size and on every
+//     ladder add. No tier is proven, so a tier configured above 25% is recorded as capped.
+//   - The tick must be fresh and listed: a sweep row, a tick time that is not a number, or a tick older than 5 min at
+//     decision time (the bs5m window) is T0.
+//   - The tier's size is the strategy's pick; every existing ceiling (strategy and profile max %, max $, per-trade loss,
+//     exposure, cash, price impact, drawdown size-down, a young-pool cap) still applies, and the stricter one wins.
+//   - One open position at a time unless the block says otherwise.
+// Refused outside paper: validateStrategy (mode real / live), the runner (a real-signal run) and the engine itself.
+//
+// The verdict, shown on every TIER line and in validation: unproven; on the held-out data no tier made money, and no
+// dexterm strategy has shown an edge (strategy synthesis, 2026-11).
+//
+// Pure: no I/O.
+export const TIER_TABLE_IDS = ['v4-1785'];
+/** The one verdict line. Printed by validation and on every TIER line. */
+export const TIERS_VERDICT = 'EXPERIMENTAL, UNPROVEN, PAPER ONLY: on our held-out data no tier made money and no dexterm strategy has shown an edge; every tier runs at 25% of the book at most.';
+/** The engine's ceiling for any tier, in % of the book. Code, not data: nothing a strategy file or table says lifts it. */
+export const TIERS_HARD_CAP_PCT = 25;
+/** A tick older than this at decision time is T0: bs5m describes a 5 min window that has moved on. */
+export const TIER_TICK_MAX_AGE_MS = 5 * 60_000;
+const freeze = (x) => {
+    if (x && typeof x === 'object') {
+        for (const v of Object.values(x))
+            freeze(v);
+        Object.freeze(x);
+    }
+    return x;
+};
+/**
+ * The frozen v4 table (schema dexterm-challenge-tiers/1, version 4.0.0), as data. The points were fitted on TRAIN only;
+ * the held-out set was scored once. Changing a number here is a new table id, never an edit.
+ */
+export const CONFIDENCE_TIERS_V4 = freeze({
+    id: 'v4-1785',
+    provenance: 'task-1785 rules v4 research (family strict): frozen 2026-10-28T03:17:49Z, held-out scored once 2026-10-28T03:18:28Z',
+    unprovenCapPct: 25,
+    reservePct: 2,
+    points: [
+        { id: 'turnover1h-max', signal: 'turnover1h', op: '<=', value: 9.878, what: '1 h volume / liquidity' },
+        { id: 'bs5m-min', signal: 'bs5m', op: '>=', value: 3.714, what: 'buys / sells, 5 min' },
+    ],
+    tiers: [
+        { id: 'T0', minScore: 0, sizePct: 0, evidence: 'skip', heldOut: { n: 19, meanPct: -17.0, loPct: -35.7, hiPct: 3.4, wins: 5, rugs: 2 } },
+        { id: 'T1', minScore: 1, sizePct: 15, evidence: 'n/a', heldOut: { n: 0, meanPct: null, loPct: null, hiPct: null, wins: null, rugs: null } },
+        { id: 'T2', minScore: 1, sizePct: 50, evidence: 'unproven', heldOut: { n: 0, meanPct: null, loPct: null, hiPct: null, wins: null, rugs: null } },
+        { id: 'T3', minScore: 1, sizePct: 75, evidence: 'unproven', heldOut: { n: 17, meanPct: -7.6, loPct: -31.8, hiPct: 16.8, wins: 5, rugs: 1 } },
+        { id: 'T4', minScore: 2, sizePct: 100, evidence: 'unproven', heldOut: { n: 0, meanPct: null, loPct: null, hiPct: null, wins: null, rugs: null } },
+    ],
+    gates: { minPoolAgeMin: 10, minLiqUsd: 30_000, youngVertical: { maxAgeHours: 2, maxH1Pct: 150 } },
+});
+export function tierTable(id) {
+    if (id === 'v4-1785')
+        return CONFIDENCE_TIERS_V4;
+    throw new Error(`unknown tier table ${String(id)}`);
+}
+const fin = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+/** Liquidity, volume and trade counts are never negative: a negative or non-finite figure is unknown. */
+const nonneg = (x) => { const v = fin(x); return v !== null && v >= 0 ? v : null; };
+/**
+ * The research's feature definitions, on one tick:
+ *   turnover1h = vol1h / liquidity (unknown when liquidity is not > 0 or vol1h is unknown)
+ *   bs5m       = buys5m / sells5m; no sells with buys = 99 (all buys); no buys and no sells = 0
+ * One difference, on the safe side: the research tape counted a missing sells figure as 0 (so buys alone gave 99);
+ * here a missing buys or sells figure makes bs5m unknown, and an unknown signal never scores its point. A negative or
+ * non-finite figure (NaN, Infinity) is unknown too.
+ */
+export function tierSignals(k) {
+    const liq = nonneg(k.liq);
+    const vol1h = nonneg(k.vol1h);
+    const b = nonneg(k.buys5m);
+    const s = nonneg(k.sells5m);
+    const turnover1h = liq !== null && liq > 0 && vol1h !== null ? vol1h / liq : null;
+    const bs5m = b === null || s === null ? null : s > 0 ? b / s : b > 0 ? 99 : 0;
+    return { liq, vol1h, turnover1h, buys5m: b, sells5m: s, bs5m };
+}
+/**
+ * The tier gates on the tick. Pool age: the tick carries the token's creation time only, and a pool is never older
+ * than its token, so a token younger than minPoolAgeMin (or of unknown age) fails here; the pair's own age is the
+ * rug-proof pool-age gate's job (validateStrategy requires it at minPoolAgeMin or more with tiers on).
+ * The tick itself: a sweep row (the coin had left the screen), a tick time that is not a number, a tick older than
+ * TIER_TICK_MAX_AGE_MS at `nowMs` or stamped after it fails. `nowMs` defaults to the tick's own time (a replay row).
+ */
+export function tierGateFailures(k, g, nowMs = k.t) {
+    const out = [];
+    const t = fin(k.t);
+    const now = fin(nowMs);
+    if (k.kind !== 'live')
+        out.push(`tick not live (${String(k.kind)})`);
+    if (t === null || now === null)
+        out.push('tick time unknown');
+    else if (now - t > TIER_TICK_MAX_AGE_MS)
+        out.push(`tick stale (${Math.ceil((now - t) / 1000)} s old > ${TIER_TICK_MAX_AGE_MS / 1000} s)`);
+    else if (t > now)
+        out.push('tick time after the decision time');
+    const created = fin(k.createdAt) !== null && k.createdAt > 0 ? k.createdAt : null;
+    const ageMin = t !== null && created !== null ? (t - created) / 60e3 : null;
+    if (ageMin === null)
+        out.push(`pool age unknown (no token creation time) < ${g.minPoolAgeMin} min`);
+    else if (ageMin < g.minPoolAgeMin)
+        out.push(`pool age < ${g.minPoolAgeMin} min (token ${ageMin.toFixed(0)} min old)`);
+    const liq = fin(k.liq);
+    if (liq === null || liq < g.minLiqUsd)
+        out.push(`liquidity ${liq === null ? 'unknown' : `$${Math.round(liq)}`} < $${g.minLiqUsd}`);
+    // A young coin with no 1 h change figure cannot be cleared of "vertical": it fails (the research tape had the figure).
+    const h1 = fin(k.chg1h);
+    if (ageMin !== null && ageMin / 60 < g.youngVertical.maxAgeHours) {
+        if (h1 === null)
+            out.push(`young and h1 unknown (at ${(ageMin / 60).toFixed(1)} h)`);
+        else if (h1 >= g.youngVertical.maxH1Pct)
+            out.push(`young and vertical (h1 ${h1}% at ${(ageMin / 60).toFixed(1)} h)`);
+    }
+    return out;
+}
+/**
+ * The size a tier runs at: never above TIERS_HARD_CAP_PCT (or the table's own cap when lower), whatever its evidence
+ * says (0.2.2 has no proven tier and no path that lifts the cap), never above 100 - reservePct. A non-finite or
+ * negative configured size runs at 0.
+ */
+export function tierRunsAtPct(t, table) {
+    const cfg = Number.isFinite(t.sizePct) && t.sizePct > 0 ? t.sizePct : 0;
+    const tableCap = Number.isFinite(table.unprovenCapPct) && table.unprovenCapPct >= 0 ? table.unprovenCapPct : 0;
+    const capPct = Math.min(TIERS_HARD_CAP_PCT, tableCap);
+    let pct = cfg;
+    let capped = false;
+    if (pct > capPct) {
+        pct = capPct;
+        capped = true;
+    }
+    if (pct > 100 - table.reservePct)
+        pct = 100 - table.reservePct;
+    return { pct, capped };
+}
+/** Score the tick (one point per rule that holds; an unknown signal never passes), then the highest tier met wins. */
+export function selectConfidenceTier(k, table = CONFIDENCE_TIERS_V4, nowMs = k.t) {
+    const sig = tierSignals(k);
+    const points = table.points.map((p) => {
+        const actual = sig[p.signal];
+        const pass = actual !== null && (p.op === '>=' ? actual >= p.value : actual <= p.value);
+        return { id: p.id, signal: p.signal, op: p.op, value: p.value, actual: actual === null ? null : Math.round(actual * 1000) / 1000, pass };
+    });
+    const score = points.filter((p) => p.pass).length;
+    const gates = tierGateFailures(k, table.gates, nowMs);
+    let row = table.tiers[0];
+    if (!gates.length)
+        for (const t of table.tiers)
+            if (score >= t.minScore)
+                row = t;
+    const run = row.id === 'T0' ? { pct: 0, capped: false } : tierRunsAtPct(row, table);
+    return { table: table.id, tier: row.id, score, of: points.length, points, gates, configuredPct: row.sizePct, effectivePct: run.pct, evidence: row.evidence, capped: run.capped, heldOut: row.heldOut };
+}
+// ───────────────────────────── text ─────────────────────────────
+const sgn = (x) => `${x > 0 ? '+' : ''}${x.toFixed(1)}`;
+/**
+ * "unproven: held-out n 17, mean -7.6% per entry, lower bound -31.8% (upper +16.8%), rug 1/17". The text carries the
+ * mean and its interval, never a win count or rate (a small-sample win rate reads as a claim the data does not make).
+ */
+export function tierEvidenceText(evidence, h) {
+    const head = evidence === 'n/a' ? 'n/a (at or under the 25% cap)' : evidence;
+    if (h.n === 0 || h.meanPct === null)
+        return `${head}: held-out n 0 (too small to say)`;
+    return `${head}: held-out n ${h.n}, mean ${h.meanPct.toFixed(1)}% per entry, lower bound ${h.loPct === null ? '?' : `${h.loPct.toFixed(1)}%`}${h.hiPct === null ? '' : ` (upper ${sgn(h.hiPct)}%)`}${h.rugs === null ? '' : `, rug ${h.rugs}/${h.n}`}`;
+}
+const short = (m) => (m.length > 10 ? `${m.slice(0, 4)}…${m.slice(-4)}` : m);
+/** The run log's TIER line: tier, score, size, evidence status and the verdict. `afterUsd` = the size after every limit. */
+export function confidenceTierLine(p, k, afterUsd) {
+    const head = `TIER ${p.tier} for ${k.symbol} (${short(k.mint)}): score ${p.score}/${p.of}`;
+    const ev = tierEvidenceText(p.evidence, p.heldOut);
+    if (p.tier === 'T0')
+        return `${head} · SKIP (size 0)${p.gates.length ? ` · gate: ${p.gates.join('; ')}` : ''} · ${ev} · ${TIERS_VERDICT}`;
+    const pts = p.points.filter((x) => x.pass).map((x) => x.id).join(', ') || 'none';
+    const size = p.capped ? `configured ${p.configuredPct}%, runs at ${p.effectivePct}% of the book (unproven: capped)` : `runs at ${p.effectivePct}% of the book`;
+    return `${head} (${pts}) · ${size}${afterUsd !== undefined ? ` · $${afterUsd} after the strategy's limits` : ''} · ${ev} · ${TIERS_VERDICT}`;
+}
+/** Validation / docs text: one line per tier, the verdict first. */
+export function tierTableLines(table = CONFIDENCE_TIERS_V4) {
+    const rows = table.tiers.map((t, i) => {
+        const run = t.id === 'T0' ? { pct: 0, capped: false } : tierRunsAtPct(t, table);
+        const unreachable = i > 0 && table.tiers.slice(i + 1).some((u) => u.minScore === t.minScore);
+        const size = t.id === 'T0' ? 'skip (size 0)' : run.capped ? `configured ${t.sizePct}%, runs at ${run.pct}% (unproven: capped)` : `runs at ${run.pct}%`;
+        return `${t.id} score >= ${t.minScore}: ${size} · ${tierEvidenceText(t.evidence, t.heldOut)}${unreachable ? ` · never selected (a higher tier has the same score ${t.minScore})` : ''}`;
+    });
+    return [TIERS_VERDICT, ...rows, `table ${table.id}: ${table.provenance}`];
+}
+/** A compact record of the pick for the ledger. */
+export function tierRecord(p) {
+    return { table: p.table, tier: p.tier, score: p.score, of: p.of, points: p.points.map((x) => ({ id: x.id, actual: x.actual, pass: x.pass })), gates: p.gates, configuredPct: p.configuredPct, runsAtPct: p.effectivePct, capped: p.capped, evidence: tierEvidenceText(p.evidence, p.heldOut) };
+}