dexterm-cli 0.1.6 → 0.2.0

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

@@ -0,0 +1,250 @@
+// dexterm autotrade — the strategy store (task-1503 AT-1, AUTOTRADE-SPEC §2c).
+//
+//   ~/.dexterm/strategies/<id>.json         one validated dexterm-strategy/1 document per strategy ($DEXTERM_HOME honoured)
+//   ~/.dexterm/strategies/.journal.jsonl    append-only audit: {t, actor, id, ops, beforeHash, afterHash, version, …}
+//   ~/.dexterm/strategies/.backtests.json   the last backtest line per strategy hash (for `list`)
+//   ~/.dexterm/strategies/.removed/         a removed strategy is moved here, never deleted
+//
+// Every write validates first (an invalid document is never written), is atomic (tmp + rename, 0600 in a
+// 0700 dir) and appends one journal line naming the actor and the before/after content hashes. The shipped
+// presets are read-only: `get` falls back to them, and editing one means `create` from it under a new id.
+// Ids are the schema's `^[a-z][a-z0-9-]{1,31}$`, checked before any path is built, so an id cannot walk out of
+// the directory. Nothing here decides who may change what: the model deny-list and the keypress live with
+// the proposal flow (AT-5); this module records the actor it is told.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyOps, dextermHome } from '../../custom/src/index.js';
+import { fmtIssue, loadStrategyFile, validateStrategy } from "./strategy.js";
+export const STRATEGY_ID = /^[a-z][a-z0-9-]{1,31}$/;
+const ACTOR = /^[a-z][a-z0-9:._-]{0,63}$/;
+/** The most ops one change may carry (the chat tool's limit, §2a). */
+export const MAX_OPS = 20;
+export const strategiesDir = (home) => join(home, 'strategies');
+const fail = (msg, path = '') => ({ ok: false, errors: [{ path, msg }], warnings: [] });
+export class StrategyStore {
+    dir;
+    journalPath;
+    now;
+    presets;
+    constructor(o = {}) {
+        this.dir = strategiesDir(o.home ?? dextermHome(o.env));
+        this.journalPath = join(this.dir, '.journal.jsonl');
+        this.now = o.now ?? Date.now;
+        this.presets = o.presetsDir ?? new URL('../assets/strategies/', import.meta.url);
+    }
+    pathOf(id) {
+        if (!STRATEGY_ID.test(id))
+            throw new Error(`bad strategy id ${JSON.stringify(id)} (lowercase letters, digits and dashes, 2-32 chars)`);
+        return join(this.dir, `${id}.json`);
+    }
+    presetFile(id) { return fileURLToPath(new URL(`${id}.json`, this.presets)); }
+    presetIds() {
+        return readdirSync(this.presets).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort();
+    }
+    userIds() {
+        if (!existsSync(this.dir))
+            return [];
+        return readdirSync(this.dir).filter((f) => f.endsWith('.json') && !f.startsWith('.') && STRATEGY_ID.test(f.slice(0, -5))).map((f) => f.slice(0, -5)).sort();
+    }
+    has(id) { return existsSync(this.pathOf(id)); }
+    /** The user's file first, else the shipped preset of that id; null when neither exists. */
+    get(id) {
+        const user = this.pathOf(id);
+        if (existsSync(user))
+            return { ...loadStrategyFile(user), source: 'user', path: user };
+        if (this.presetIds().includes(id)) {
+            const p = this.presetFile(id);
+            return { ...loadStrategyFile(p), source: 'preset', path: p };
+        }
+        return null;
+    }
+    /** The raw document as stored (user file, else preset), for edits. */
+    raw(id) {
+        const user = this.pathOf(id);
+        const path = existsSync(user) ? user : this.presetIds().includes(id) ? this.presetFile(id) : null;
+        if (!path)
+            return null;
+        try {
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    list() {
+        const last = this.backtests();
+        const users = this.userIds();
+        const entry = (id, source) => {
+            const r = loadStrategyFile(source === 'user' ? this.pathOf(id) : this.presetFile(id));
+            if (!r.ok)
+                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,
+                ...(last[s.hash] ? { lastBacktest: last[s.hash] } : {}),
+            };
+        };
+        const presets = this.presetIds();
+        return [
+            ...presets.filter((id) => !users.includes(id)).map((id) => entry(id, 'preset')),
+            ...users.map((id) => ({ ...entry(id, 'user'), ...(presets.includes(id) ? { shadowsPreset: true } : {}) })),
+        ];
+    }
+    /** Create a new user strategy from a document (its `id` names the file). Refuses an existing id. */
+    create(doc, o) {
+        const id = doc?.id;
+        if (typeof id !== 'string' || !STRATEGY_ID.test(id))
+            return fail('the document needs a valid id (lowercase letters, digits and dashes, 2-32 chars)', '/id');
+        if (this.has(id))
+            return fail(`a strategy ${id} already exists in ${this.dir} (edit it, or pick another id)`, '/id');
+        return this.write(id, doc, null, { ...o, action: 'create', ops: [{ op: 'add', path: '', value: doc }] });
+    }
+    /** Copy a preset or a stored strategy under a new id (and name). */
+    createFrom(fromId, newId, o) {
+        const base = this.raw(fromId);
+        if (!base)
+            return fail(`no strategy or preset ${fromId}`);
+        const doc = { ...base, id: newId, version: '1.0.0', ...(o.name ? { name: o.name } : {}) };
+        return this.create(doc, { actor: o.actor, why: o.why, from: fromId });
+    }
+    /** Replace a user strategy with a whole new document (same id). The version must go up. */
+    update(id, doc, o) {
+        if (!this.has(id))
+            return fail(`no user strategy ${id} (presets are read-only: create a copy first)`);
+        if (doc?.id !== id)
+            return fail(`the document id must stay ${id}`, '/id');
+        return this.write(id, doc, this.currentHash(id), { ...o, action: 'update', ops: [{ op: 'replace', path: '', value: doc }] });
+    }
+    /**
+     * Apply JSON-patch ops (≤ MAX_OPS) to a user strategy. The patch version is bumped unless the ops set
+     * `/version` themselves; `/id` cannot change. The journal line carries the ops and their inverse.
+     */
+    patch(id, ops, o) {
+        if (!this.has(id))
+            return fail(`no user strategy ${id} (presets are read-only: create a copy first)`);
+        if (!Array.isArray(ops) || ops.length === 0)
+            return fail('no ops');
+        if (ops.length > MAX_OPS)
+            return fail(`${ops.length} ops is more than ${MAX_OPS} in one change`);
+        if (ops.some((x) => x.path === '/id' || x.path === ''))
+            return fail('the id and the whole document cannot be patched', '/id');
+        const before = this.raw(id);
+        if (!before)
+            return fail(`${id} is not readable JSON`);
+        let next, inverse;
+        try {
+            ({ doc: next, inverse } = applyOps(before, ops));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+        if (!ops.some((x) => x.path === '/version'))
+            next = { ...next, version: bumpPatch(before.version) };
+        return this.write(id, next, this.currentHash(id), { ...o, action: 'patch', ops, inverse });
+    }
+    /** Move a user strategy to .removed/ (never deleted) and journal it. */
+    remove(id, o) {
+        if (!this.has(id))
+            return fail(`no user strategy ${id}`);
+        const t = this.now();
+        const before = this.currentHash(id);
+        const dest = join(this.dir, '.removed');
+        mkdirSync(dest, { recursive: true, mode: 0o700 });
+        const movedTo = join(dest, `${id}.${t}.json`);
+        renameSync(this.pathOf(id), movedTo);
+        const journal = { t, actor: checkActor(o.actor), id, action: 'remove', ops: [{ op: 'remove', path: '' }], beforeHash: before, afterHash: null, version: null, ...(o.why ? { why: o.why } : {}) };
+        this.append(journal);
+        return { ok: true, journal, movedTo };
+    }
+    journal(id) {
+        if (!existsSync(this.journalPath))
+            return [];
+        const out = [];
+        for (const l of readFileSync(this.journalPath, 'utf8').split('\n')) {
+            if (!l.trim())
+                continue;
+            try {
+                const j = JSON.parse(l);
+                if (!id || j.id === id)
+                    out.push(j);
+            }
+            catch { /* a torn last line is skipped, never rewritten */ }
+        }
+        return out;
+    }
+    backtests() {
+        const p = join(this.dir, '.backtests.json');
+        if (!existsSync(p))
+            return {};
+        try {
+            return JSON.parse(readFileSync(p, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Remember the last backtest of a strategy hash (shown by `list`; a changed strategy has a new hash). */
+    recordBacktest(line) {
+        const all = this.backtests();
+        all[line.hash] = line;
+        const keep = Object.values(all).sort((a, b) => b.t - a.t).slice(0, 200);
+        this.atomic(join(this.dir, '.backtests.json'), JSON.stringify(Object.fromEntries(keep.map((b) => [b.hash, b])), null, 2) + '\n');
+    }
+    // ───────────────────────────── internals ─────────────────────────────
+    currentHash(id) {
+        const r = loadStrategyFile(this.pathOf(id));
+        return r.ok ? r.strategy.hash : null;
+    }
+    write(id, doc, beforeHash, o) {
+        let actor;
+        try {
+            actor = checkActor(o.actor);
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+        const r = validateStrategy(doc);
+        if (!r.ok)
+            return r;
+        const prev = this.has(id) ? this.raw(id) : null;
+        if (prev && o.action !== 'create' && !semverGreater(r.strategy.version, prev.version))
+            return { ok: false, errors: [{ path: '/version', msg: `version ${r.strategy.version} must be above the stored ${prev.version}` }], warnings: r.warnings };
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        this.atomic(this.pathOf(id), JSON.stringify(doc, null, 2) + '\n');
+        const journal = {
+            t: this.now(), actor, id, action: o.action, ops: o.ops, ...(o.inverse ? { inverse: o.inverse } : {}),
+            beforeHash, afterHash: r.strategy.hash, version: r.strategy.version,
+            ...(o.why ? { why: o.why.slice(0, 400) } : {}), ...(o.proposalId ? { proposalId: o.proposalId } : {}), ...(o.from ? { from: o.from } : {}),
+        };
+        this.append(journal);
+        return { ok: true, strategy: r.strategy, warnings: r.warnings, journal };
+    }
+    append(j) {
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        appendFileSync(this.journalPath, `${JSON.stringify(j)}\n`, { mode: 0o600 });
+    }
+    atomic(path, text) {
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        const tmp = `${path}.tmp-${process.pid}`;
+        writeFileSync(tmp, text, { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+}
+function checkActor(a) {
+    if (typeof a !== 'string' || !ACTOR.test(a))
+        throw new Error(`bad actor ${JSON.stringify(a)}`);
+    return a;
+}
+export function bumpPatch(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v);
+    return m ? `${m[1]}.${m[2]}.${Number(m[3]) + 1}` : '1.0.1';
+}
+export function semverGreater(a, b) {
+    const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++)
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) > (pb[i] ?? 0);
+    return false;
+}
+export const fmtIssues = (xs) => xs.map(fmtIssue).join('; ');

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

@@ -0,0 +1,258 @@
+// dexterm autotrade — the strategy document (task-1498 spike, AUTOTRADE-SPEC §1).
+//
+// One declarative, versioned JSON document says everything an autotrade run may do: which coins are
+// candidates (the screener filter grammar plus safety gates and triggers), how a position is exited (exit
+// profiles, the challenge-kit model extended with `wake`), how much loss is allowed, how a size is picked,
+// and what the per-candidate agent session may spend. The engine, the clamp, the monitor and the backtester
+// all read this one document, so a backtest and a paper run of the same file make the same decisions.
+//
+// Validation is the zero-dependency subset validator from @dexterm/custom plus the cross-field rules a
+// schema cannot say. Nothing in here can name a key, a wallet or the signer: closed objects make an attempt
+// to add one a precise refusal, and `mode: "live"` validates but is refused by the runner (paper only).
+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";
+export const STRATEGY_SCHEMA = 'dexterm-strategy/1';
+export const EXIT_PROFILE_VERSION = '1.2.0';
+// ───────────────────────────── schema ─────────────────────────────
+const ID = '^[a-z][a-z0-9-]{1,31}$';
+const SEMVER = '^[0-9]+\\.[0-9]+\\.[0-9]+$';
+const num = (min, max, int = false) => ({ type: 'number', min, max, int });
+const str = (max, pattern) => ({ type: 'string', max, pattern });
+const obj = (props, required = Object.keys(props)) => ({ type: 'object', additional: false, required, props });
+const nullable = (n) => ({ oneOf: [{ type: 'null' }, n] });
+const ageRange = obj({ min: num(0, 8760), max: nullable(num(0, 8760)) });
+export const SCHEMAS = {
+    exitProfile: obj({
+        kind: { type: 'string', enum: ['exit-profile'] },
+        id: str(32, ID), name: str(40), version: str(16, SEMVER), description: str(400),
+        fit: obj({ summary: str(300), minLiquidityUsd: num(1000), ageHours: ageRange, maxTop10Pct: nullable(num(0, 100)), signals: { type: 'array', items: str(200), max: 8 } }, ['summary', 'minLiquidityUsd', 'ageHours']),
+        sizing: obj({ maxSizePctOfBankroll: num(0.1, 25) }),
+        tpLadder: { type: 'array', max: 6, items: obj({ atPct: num(0.1, 10000), sellFrac: num(0.01, 1) }) },
+        trailingStop: nullable(obj({ armAtPct: num(0), trailPct: num(5, 60) })),
+        timeStop: nullable(obj({ minutes: num(1, 10080), ifBelowPct: num(-100, 10000), action: { type: 'string', enum: ['exit', 'review', 'tighten'] } })),
+        hardStop: obj({ enabled: { type: 'boolean' }, atPct: nullable(num(-90, 0)), why: str(400) }),
+        thesisBreak: obj({
+            liquidityDropPct: num(5, 90), liquidityWindowMin: num(1, 60), mcapDivergenceX: nullable(num(1.5)),
+            devSell: obj({ exitOnAnyDevSell: { type: 'boolean' }, topHolderSellPctOfBag: nullable(num(1, 100)) }),
+            volumeDeath: nullable(obj({ m5TradesBelow: num(1, 10000, true), forMinutes: num(1, 1440) })),
+        }),
+        reentry: obj({ allowed: { type: 'boolean' }, cooldownMinutes: num(0, 10080), maxEntriesPerCoinPerSession: num(1, 5, true), requires: str(300) }),
+        carry: obj({ allowed: { type: 'boolean' }, requiresTpFilled: num(0, 6, true), maxRemainderPctOfBankroll: num(0, 25) }),
+        reprofileTo: { type: 'array', max: 8, items: str(32, ID) },
+        wake: obj({ onTpFilled: { type: 'boolean' }, onTimeReview: { type: 'boolean' }, drawdownPct: nullable(num(-95, -1)), thesisWarnFrac: nullable(num(0.1, 0.95)), noAnswer: { type: 'string', enum: ['hold', 'exit'] }, onCostRecovered: { type: 'boolean' } }, ['onTpFilled', 'onTimeReview', 'drawdownPct', 'thesisWarnFrac', 'noAnswer']),
+        costRecovery: nullable(obj({ atPct: num(10, 10000), maxSellFrac: num(0.1, 0.9) })),
+        bagTrail: nullable(obj({ trailPct: num(10, 90), armAtPct: num(0, 100000) }, ['trailPct'])),
+        maxHoldMinutes: nullable(num(1, 43200)),
+        notes: { type: 'array', max: 8, items: str(300) },
+    }, ['kind', 'id', 'name', 'version', 'description', 'fit', 'sizing', 'tpLadder', 'trailingStop', 'timeStop', 'hardStop', 'thesisBreak', 'reentry', 'carry', 'reprofileTo']),
+    trigger: {
+        oneOf: [
+            obj({ kind: { type: 'string', enum: ['screen'] } }),
+            obj({ kind: { type: 'string', enum: ['momentum'] }, m5MinPct: num(-100, 10000), buySellMin: num(0, 100) }),
+            obj({ kind: { type: 'string', enum: ['narrative'] }, minHeat: num(0, 100) }),
+            obj({ kind: { type: 'string', enum: ['wallet'] }, list: { type: 'string', enum: ['followed'] }, minBuyUsd: num(0, 1e7) }),
+        ],
+    },
+    strategy: obj({
+        kind: { type: 'string', enum: ['strategy'] },
+        schema: { type: 'string', enum: [STRATEGY_SCHEMA] },
+        id: str(32, ID), name: str(40), version: str(16, SEMVER), description: str(600),
+        mode: { type: 'string', enum: ['paper', 'real', 'live'] },
+        highRisk: { type: 'boolean' },
+        bankroll: obj({ startUsd: num(1, 1e7), source: { type: 'string', enum: ['fixed', 'desk'] } }, ['startUsd']),
+        entry: obj({
+            screen: str(400),
+            ageHours: ageRange,
+            safety: obj({
+                maxTop10Pct: nullable(num(0, 100)), maxDevPct: nullable(num(0, 100)),
+                requireNoMintAuthority: { type: 'boolean' }, requireNoFreezeAuthority: { type: 'boolean' },
+                maxMcapSplitX: nullable(num(1.5, 100)),
+                youngVertical: nullable(obj({ maxAgeHours: num(0, 168), maxH1Pct: num(0, 100000) })),
+                unknownHolders: { type: 'string', enum: ['reject', 'allow'] },
+                larp: nullable(obj({ maxScore: num(0, 100), unknown: { type: 'string', enum: ['reject', 'allow'] } })),
+            }, ['maxTop10Pct', 'maxDevPct', 'requireNoMintAuthority', 'requireNoFreezeAuthority', 'maxMcapSplitX', 'youngVertical', 'unknownHolders']),
+            triggers: { type: 'array', max: 8, items: 'trigger' },
+            triggerMode: { type: 'string', enum: ['any', 'all'] },
+            decide: { type: 'string', enum: ['agent', 'auto', 'agent+approve'] },
+            candidateTtlSec: num(10, 3600),
+        }),
+        exits: obj({ default: str(32, ID), profiles: { type: 'array', max: 8, items: { oneOf: [str(48, '^builtin:[a-z][a-z0-9-]{1,31}$'), 'exitProfile'] } } }),
+        sizing: obj({
+            mode: { type: 'string', enum: ['fixed', 'pct', 'risk', 'confidence'] },
+            fixedUsd: num(1, 1e6), pct: num(0.1, 25), riskPct: num(0.1, 10),
+            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),
+        }, ['mode', 'maxPctOfBankroll', 'maxUsd', 'minUsd']),
+        risk: obj({
+            perTrade: obj({ maxLossPctOfBankroll: num(0.1, 25), assumedLossPctNoStop: num(10, 100) }),
+            dailyLossHaltPct: num(1, 100),
+            drawdown: obj({ sizeDownAtPct: num(1, 100), sizeDownMult: num(0.05, 1), recoverBelowPct: num(0, 100), haltAtPct: num(1, 100) }),
+            maxConcurrent: num(1, 20, true), maxExposurePct: num(1, 100),
+            lossStreak: obj({ losses: num(1, 50, true), cooldownMin: num(0, 10080) }),
+            maxEntriesPerDay: num(1, 500, true),
+            perCoin: obj({ maxEntries: num(1, 20, true), cooldownMin: num(0, 10080) }),
+            recoveredBags: obj({ countAsOpen: { type: 'boolean' }, maxBags: num(0, 50, true) }),
+        }, ['perTrade', 'dailyLossHaltPct', 'drawdown', 'maxConcurrent', 'maxExposurePct', 'lossStreak', 'maxEntriesPerDay', 'perCoin']),
+        agent: obj({
+            model: str(64, '^[a-z0-9][a-z0-9.-]{1,63}$'), maxSessions: num(1, 8, true),
+            budgetUsdPerSession: num(0.01, 50), budgetUsdPerDay: num(0.01, 500), maxTurns: num(1, 1000, true),
+            deltaEverySec: num(1, 600), decideWithinSec: num(5, 3600), sessionMaxMin: num(1, 1440),
+            onTimeout: { type: 'string', enum: ['skip'] },
+            respawnOnWake: { type: 'boolean' },
+        }, ['model', 'maxSessions', 'budgetUsdPerSession', 'budgetUsdPerDay', 'maxTurns', 'deltaEverySec', 'decideWithinSec', 'sessionMaxMin', 'onTimeout']),
+        execution: obj({ slippageBps: num(0, 5000), feeBps: num(0, 1000), networkFeeUsd: num(0, 10), latencyMs: num(0, 120000), maxPriceImpactPct: num(0.1, 50), minExitLiquidityUsd: num(0, 1e7) }),
+        notes: { type: 'array', max: 8, items: str(300) },
+    }, ['kind', 'schema', 'id', 'name', 'version', 'description', 'mode', 'bankroll', 'entry', 'exits', 'sizing', 'risk', 'agent', 'execution']),
+};
+/** Schema + the cross-field rules for one exit profile. */
+export function validateExitProfile(p, at = '') {
+    const errs = validate('exitProfile', p, at, [], SCHEMAS);
+    if (errs.length)
+        return errs;
+    const x = p;
+    for (let i = 1; i < x.tpLadder.length; i++)
+        if (!(x.tpLadder[i].atPct > x.tpLadder[i - 1].atPct))
+            errs.push({ path: `${at}/tpLadder/${i}`, msg: 'atPct must be strictly ascending' });
+    const sum = x.tpLadder.reduce((s, t) => s + t.sellFrac, 0);
+    if (sum > 1 + 1e-9)
+        errs.push({ path: `${at}/tpLadder`, msg: `sellFrac adds up to ${round(sum, 4)} (more than the whole position)` });
+    if (x.hardStop.enabled && x.hardStop.atPct === null)
+        errs.push({ path: `${at}/hardStop/atPct`, msg: 'an enabled hard stop needs atPct' });
+    if (x.carry.allowed && x.carry.maxRemainderPctOfBankroll <= 0)
+        errs.push({ path: `${at}/carry`, msg: 'carry allowed needs maxRemainderPctOfBankroll > 0' });
+    if (x.bagTrail && !x.costRecovery)
+        errs.push({ path: `${at}/bagTrail`, msg: 'a bag trail is armed by the cost-recovery sell: set costRecovery' });
+    if (x.costRecovery && x.tpLadder.length && x.tpLadder[0].atPct <= x.costRecovery.atPct)
+        errs.push({ path: `${at}/tpLadder/0`, msg: 'a TP step at or below the cost-recovery level would sell first: put the ladder above costRecovery.atPct' });
+    if (x.reprofileTo.includes(x.id))
+        errs.push({ path: `${at}/reprofileTo`, msg: 'a profile cannot re-profile to itself' });
+    return errs;
+}
+/** Load the shipped exit-profile library (assets/autotrade/profiles). */
+export function builtinProfiles(dir = new URL('../assets/profiles/', import.meta.url)) {
+    const out = {};
+    for (const f of readdirSync(dir).filter((x) => x.endsWith('.json')).sort()) {
+        const p = JSON.parse(readFileSync(new URL(f, dir), 'utf8'));
+        const errs = validateExitProfile(p);
+        if (errs.length)
+            throw new Error(`builtin profile ${f} is invalid: ${errs.map(fmtIssue).join('; ')}`);
+        out[p.id] = p;
+    }
+    return out;
+}
+/**
+ * Validate a strategy document and resolve its profile references. Never throws on bad input: every
+ * problem comes back as a path + message so the TUI editor and the assistant's tool can show it inline.
+ */
+export function validateStrategy(doc, library = builtinProfiles()) {
+    const warnings = [];
+    const errors = validate('strategy', doc, '', [], SCHEMAS);
+    if (errors.length)
+        return { ok: false, errors, warnings };
+    const s = doc;
+    const f = parseFilter(s.entry.screen);
+    if (!f.ok)
+        errors.push({ path: '/entry/screen', msg: `${f.error} (column ${f.at})` });
+    const profiles = {};
+    s.exits.profiles.forEach((ref, i) => {
+        const p = typeof ref === 'string' ? library[ref.slice('builtin:'.length)] : ref;
+        if (!p) {
+            errors.push({ path: `/exits/profiles/${i}`, msg: `unknown builtin profile ${String(ref)}` });
+            return;
+        }
+        errors.push(...validateExitProfile(p, `/exits/profiles/${i}`));
+        if (profiles[p.id])
+            errors.push({ path: `/exits/profiles/${i}`, msg: `duplicate profile id ${p.id}` });
+        profiles[p.id] = p;
+    });
+    if (!profiles[s.exits.default])
+        errors.push({ path: '/exits/default', msg: `default profile ${s.exits.default} is not in exits.profiles` });
+    for (const p of Object.values(profiles)) {
+        for (const t of p.reprofileTo)
+            if (!profiles[t])
+                warnings.push({ path: '/exits/profiles', msg: `${p.id} may re-profile to ${t}, which this strategy does not include (that edge is unused)` });
+        if (p.sizing.maxSizePctOfBankroll < s.sizing.maxPctOfBankroll)
+            warnings.push({ path: '/sizing/maxPctOfBankroll', msg: `profile ${p.id} caps a position at ${p.sizing.maxSizePctOfBankroll}% (the lower cap wins)` });
+    }
+    const z = s.sizing;
+    const need = (k, mode) => { if (z.mode === mode && z[k] === undefined)
+        errors.push({ path: `/sizing/${k}`, msg: `sizing mode ${mode} needs ${k}` }); };
+    need('fixedUsd', 'fixed');
+    need('pct', 'pct');
+    need('riskPct', 'risk');
+    need('confidence', 'confidence');
+    if (z.confidence && z.confidence.minPct > z.confidence.maxPct)
+        errors.push({ path: '/sizing/confidence', msg: 'minPct is above maxPct' });
+    if (z.minUsd > z.maxUsd)
+        errors.push({ path: '/sizing/minUsd', msg: 'minUsd is above maxUsd' });
+    if (z.ladder) {
+        const sum = z.ladder.reduce((a, t) => a + t.frac, 0);
+        if (Math.abs(sum - 1) > 1e-6)
+            errors.push({ path: '/sizing/ladder', msg: `tranche fractions add up to ${round(sum, 4)}, they must add up to 1` });
+        if (z.ladder[0] && z.ladder[0].atPct !== 0)
+            errors.push({ path: '/sizing/ladder/0/atPct', msg: 'the first tranche fills at entry (atPct 0)' });
+    }
+    const r = s.risk;
+    if (r.drawdown.sizeDownAtPct > r.drawdown.haltAtPct)
+        errors.push({ path: '/risk/drawdown', msg: 'sizeDownAtPct must not exceed haltAtPct' });
+    if (r.drawdown.recoverBelowPct >= r.drawdown.sizeDownAtPct)
+        errors.push({ path: '/risk/drawdown/recoverBelowPct', msg: 'recoverBelowPct must be below sizeDownAtPct' });
+    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)
+        errors.push({ path: '/entry/ageHours', msg: 'max is below min' });
+    if (s.entry.triggers.length === 0)
+        errors.push({ path: '/entry/triggers', msg: 'at least one trigger (use {"kind":"screen"} for "every screen match")' });
+    for (const [i, t] of s.entry.triggers.entries())
+        if (t.kind === 'narrative' || t.kind === 'wallet')
+            warnings.push({ path: `/entry/triggers/${i}`, msg: `${t.kind} triggers need the live ${t.kind} feed; replays and backtests treat them as not firing` });
+    if (s.bankroll.source === 'desk')
+        warnings.push({ path: '/bankroll/source', msg: 'desk reads the paper desk book during a run; backtests use startUsd' });
+    if (s.entry.safety.larp)
+        warnings.push({ path: '/entry/safety/larp', msg: 'the LARP gate needs the live web (live data runs only); replays and backtests do not evaluate it' });
+    if (s.mode === 'real')
+        warnings.push({ path: '/mode', msg: 'mode real sends a LIVE TRADE FIRE signal for every trade to your own executor; it runs only after `dexterm autotrade signal arm` on your own terminal, at this exact version' });
+    if (s.mode === 'live')
+        warnings.push({ path: '/mode', msg: 'mode live does not run: dexterm runs strategies on paper only (it holds no key and places no live order); live trading happens in the Telegram trading bot of your choice' });
+    if (errors.length)
+        return { ok: false, errors, warnings };
+    const resolved = { ...s, exits: { default: s.exits.default, profiles } };
+    return { ok: true, strategy: { ...resolved, hash: strategyHash(resolved) }, warnings };
+}
+/** Stable content hash (sorted keys) written into every audit line so a decision names its exact rules. */
+export function strategyHash(s) {
+    return createHash('sha256').update(canonical(s)).digest('hex').slice(0, 16);
+}
+export function canonical(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(',')}]`;
+    const o = v;
+    return `{${Object.keys(o).filter((k) => o[k] !== undefined && k !== 'hash').sort().map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`).join(',')}}`;
+}
+export function loadStrategyFile(path, library) {
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        return { ok: false, errors: [{ path: '', msg: `not JSON: ${e.message}` }], warnings: [] };
+    }
+    return validateStrategy(doc, library);
+}
+/** The shipped presets (assets/autotrade/strategies). */
+export function presetPath(id) {
+    return new URL(`../assets/strategies/${id}.json`, import.meta.url);
+}
+export function loadPreset(id) {
+    const r = loadStrategyFile(presetPath(id));
+    if (!r.ok)
+        throw new Error(`preset ${id} is invalid: ${r.errors.map(fmtIssue).join('; ')}`);
+    return r.strategy;
+}
+export const fmtIssue = (i) => `${i.path || '/'}: ${i.msg}`;
+export const round = (x, dp = 2) => Math.round(x * 10 ** dp) / 10 ** dp;