Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Exit Lab replay kernel.
//
// These pin the properties that make the tool trustworthy rather than merely
// plausible: a replay must never invent value the recorded path did not contain,
// a bounded (still-holding) result must be flagged as a lower bound, and a
// laddered policy must never sell the last of a winner.
import { describe, it, expect } from 'vitest';
import {
replayPosition,
replayFleet,
sweepParams,
normalizeParams,
sameParams,
exitReasons,
toSol,
PARAM_SPECS,
DEFAULT_PARAMS,
LAMPORTS_PER_SOL,
} from '../api/_lib/exit-replay.js';
const SOL = LAMPORTS_PER_SOL;
/** A position that 3x'd and came back to 1.2x. */
const winner = {
mint: 'THREEsynthetic1111111111111111111111111111',
symbol: 'WIN',
entryLamports: 0.02 * SOL,
peakLamports: 0.06 * SOL,
terminalLamports: 0.024 * SOL,
actualPnlLamports: 0.001 * SOL,
actualReason: 'trailing_stop',
};
/** A position that never went green and bled out. */
const loser = {
mint: 'THREEsynthetic2222222222222222222222222222',
symbol: 'LOSS',
entryLamports: 0.02 * SOL,
peakLamports: 0.02 * SOL,
terminalLamports: 0.01 * SOL,
actualPnlLamports: -0.01 * SOL,
actualReason: 'timeout',
};
describe('normalizeParams', () => {
it('clamps an out-of-range value to the spec instead of throwing', () => {
const p = normalizeParams({ stopLossPct: 9999, moonbagMinPct: -50 });
const sl = PARAM_SPECS.find((s) => s.key === 'stopLossPct');
const mb = PARAM_SPECS.find((s) => s.key === 'moonbagMinPct');
expect(p.stopLossPct).toBe(sl.max);
expect(p.moonbagMinPct).toBe(mb.min);
});
it('reads a missing nullable knob as off, not as zero', () => {
// Number(null) === 0 and a 0% stop-loss fires immediately, so this
// distinction is the difference between "no stop" and "sell everything".
expect(normalizeParams({}).takeProfitPct).toBeNull();
expect(normalizeParams({}).stopLossPct).toBeNull();
});
it('falls back to the live default for a non-nullable knob', () => {
expect(normalizeParams({}).moonbagMinPct).toBe(DEFAULT_PARAMS.moonbagMinPct);
});
it('treats an unparseable value as absent rather than NaN', () => {
expect(normalizeParams({ stopLossPct: 'banana' }).stopLossPct).toBeNull();
});
it('compares policies by value', () => {
expect(sameParams(DEFAULT_PARAMS, { ...DEFAULT_PARAMS })).toBe(true);
expect(sameParams(DEFAULT_PARAMS, { ...DEFAULT_PARAMS, stopLossPct: 10 })).toBe(false);
});
});
describe('replayPosition', () => {
it('refuses a position with no cost basis instead of returning a zero', () => {
const r = replayPosition({ entryLamports: 0, peakLamports: 1, terminalLamports: 1 }, DEFAULT_PARAMS);
expect(r.ok).toBe(false);
expect(r.skip).toBe('no_entry_basis');
});
it('refuses a position with no recorded price path', () => {
const r = replayPosition({ entryLamports: SOL, peakLamports: null, terminalLamports: null }, DEFAULT_PARAMS);
expect(r.ok).toBe(false);
expect(r.skip).toBe('no_price_path');
});
it('takes initials at the ladder multiple and keeps a bag riding', () => {
const r = replayPosition(winner, { ...DEFAULT_PARAMS, initialsOutMultiple: 2, trailingStopPct: null, stopLossPct: null });
const initials = r.legs.find((l) => l.reason === 'take_initials');
expect(initials).toBeDefined();
expect(initials.atMultiple).toBeCloseTo(2, 2);
// At 2x the ladder sells exactly enough to recover the stake, capped by the
// moon-bag floor: half the bag.
expect(initials.sellFraction).toBeCloseTo(0.5, 2);
expect(r.openValueLamports).toBeGreaterThan(0);
});
it('never sells the whole bag of a position that is in profit', () => {
const r = replayPosition(winner, DEFAULT_PARAMS);
const sold = r.legs.reduce((acc, l) => acc + l.sellFraction, 0);
expect(sold).toBeLessThan(2); // two legs can never both be a full exit
expect(r.openValueLamports).toBeGreaterThan(0);
});
it('exits a full loser at the hard stop and books the loss there', () => {
const r = replayPosition(loser, { ...DEFAULT_PARAMS, stopLossPct: 35 });
expect(r.exitReason).toBe('stop_loss');
// A stop on money still at risk is a full exit; nothing may ride.
expect(r.openValueLamports).toBe(0);
expect(r.pnlLamports).toBeLessThan(0);
// The stop fires at 35% down, so the loss is bounded there and is NOT the
// full drop to the terminal price.
expect(r.pnlPct).toBeCloseTo(-35, 0);
});
it('holds to the end of the recorded path when nothing fires, and says the result is bounded', () => {
const r = replayPosition(loser, { stopLossPct: null, trailingStopPct: null, takeProfitPct: null, initialsOutMultiple: null, moonbagMinPct: 0 });
expect(r.bounded).toBe(true);
expect(r.totalLamports).toBeCloseTo(loser.terminalLamports, 0);
});
it('never values a bag above the last price actually observed', () => {
const r = replayPosition(winner, DEFAULT_PARAMS);
// Total proceeds can never exceed selling the entire bag at the peak.
expect(r.totalLamports).toBeLessThanOrEqual(winner.peakLamports + 1);
});
it('clamps an incoherent row where the peak sits below the terminal price', () => {
// A sweep that raced the exit can write a peak under the final quote. The
// replay clamps rather than walking a path that never existed.
const r = replayPosition(
{ entryLamports: SOL, peakLamports: 0.5 * SOL, terminalLamports: 3 * SOL },
DEFAULT_PARAMS,
);
expect(r.ok).toBe(true);
expect(r.peakMultiple).toBeGreaterThanOrEqual(r.terminalMultiple);
});
it('is deterministic: the same inputs replay to the same numbers', () => {
const a = replayPosition(winner, DEFAULT_PARAMS);
const b = replayPosition(winner, DEFAULT_PARAMS);
expect(a).toEqual(b);
});
it('takes no clock from the environment', () => {
// max_hold_seconds is deliberately not part of the replay: the recorded
// path already ends where the real position ended, so a timeout clock would
// double-count the hold. A policy therefore cannot depend on Date.now().
const before = replayPosition(winner, DEFAULT_PARAMS);
const spy = Date.now;
Date.now = () => 0;
const after = replayPosition(winner, DEFAULT_PARAMS);
Date.now = spy;
expect(after).toEqual(before);
});
});
describe('replayFleet', () => {
const corpus = [winner, loser];
it('aggregates only replayable rows and counts the rest as skipped', () => {
const r = replayFleet([...corpus, { entryLamports: 0 }], DEFAULT_PARAMS);
expect(r.trades).toBe(2);
expect(r.skipped).toBe(1);
});
it('reports the actual booked result over the same corpus for comparison', () => {
const r = replayFleet(corpus, DEFAULT_PARAMS);
expect(r.actual.knownTrades).toBe(2);
expect(r.actual.pnlLamports).toBe(winner.actualPnlLamports + loser.actualPnlLamports);
});
it('leaves a position with no booked P&L out of the actual total rather than counting it as zero', () => {
const unknown = { ...winner, mint: 'THREEsynthetic3333333333333333333333333333', actualPnlLamports: null };
const r = replayFleet([unknown], DEFAULT_PARAMS);
expect(r.trades).toBe(1);
expect(r.actual.knownTrades).toBe(0);
expect(r.actual.pnlLamports).toBe(0);
});
it('builds a cumulative curve with one point per trade', () => {
const r = replayFleet(corpus, DEFAULT_PARAMS);
expect(r.curve).toHaveLength(2);
expect(r.curve[1]).toBe(r.pnlLamports);
});
it('reports a non-negative drawdown', () => {
const r = replayFleet(corpus, DEFAULT_PARAMS);
expect(r.maxDrawdownLamports).toBeGreaterThanOrEqual(0);
});
it('attributes every counted trade to a known exit reason', () => {
const r = replayFleet(corpus, DEFAULT_PARAMS);
const attributed = Object.values(r.byReason).reduce((acc, v) => acc + v.trades, 0);
expect(attributed).toBe(r.trades);
for (const key of Object.keys(r.byReason)) expect(exitReasons()).toContain(key);
});
it('returns an honest zero on an empty corpus instead of throwing', () => {
const r = replayFleet([], DEFAULT_PARAMS);
expect(r.trades).toBe(0);
expect(r.pnlLamports).toBe(0);
expect(r.winRate).toBe(0);
expect(r.rows).toEqual([]);
});
it('tolerates a non-array corpus', () => {
expect(replayFleet(null, DEFAULT_PARAMS).trades).toBe(0);
});
it('a tighter stop can only reduce the loss on a pure loser', () => {
const wide = replayFleet([loser], { ...DEFAULT_PARAMS, stopLossPct: 70 });
const tight = replayFleet([loser], { ...DEFAULT_PARAMS, stopLossPct: 15 });
expect(tight.pnlLamports).toBeGreaterThan(wide.pnlLamports);
});
});
describe('sweepParams', () => {
const corpus = [winner, loser];
it('enumerates the full grid exactly', () => {
const s = sweepParams(corpus, { stopLossPct: [10, 20, 30], trailingStopPct: [10, 25] }, { limit: 99 });
expect(s.combos).toBe(6);
expect(s.leaders).toHaveLength(6);
});
it('ranks leaders by profit, best first', () => {
const s = sweepParams(corpus, { stopLossPct: [10, 20, 30, 50, 70] }, { limit: 5 });
const pnls = s.leaders.map((l) => l.pnlLamports);
expect([...pnls].sort((a, b) => b - a)).toEqual(pnls);
});
it('flags overfit risk on a corpus too thin to lean on', () => {
expect(sweepParams(corpus, { stopLossPct: [10, 20] }).overfitRisk).toBe(true);
});
it('does not flag overfit risk once the corpus is deep enough', () => {
const deep = Array.from({ length: 40 }, (_, i) => ({ ...winner, mint: `mint${i}` }));
expect(sweepParams(deep, { stopLossPct: [10, 20] }).overfitRisk).toBe(false);
});
it('ignores an axis that is not a real parameter', () => {
const s = sweepParams(corpus, { notAKnob: [1, 2, 3] }, { limit: 5 });
expect(s.combos).toBe(1);
});
it('reports the baseline alongside the leaders so a win is measurable', () => {
const s = sweepParams(corpus, { stopLossPct: [10, 20] });
expect(s.baseline.params).toEqual(normalizeParams(DEFAULT_PARAMS));
expect(typeof s.baseline.pnlLamports).toBe('number');
});
});
describe('PARAM_SPECS', () => {
it('gives every knob a range, a step and a plain-language explanation', () => {
for (const spec of PARAM_SPECS) {
expect(spec.min).toBeLessThan(spec.max);
expect(spec.step).toBeGreaterThan(0);
expect(spec.help.length).toBeGreaterThan(40);
expect(spec.help).not.toMatch(/[\u2013\u2014]/); // the repo dash ban applies to UI copy
}
});
it('has a live default inside its own declared range for every knob', () => {
for (const spec of PARAM_SPECS) {
const v = DEFAULT_PARAMS[spec.key];
if (v == null) {
expect(spec.nullable).toBe(true);
continue;
}
expect(v).toBeGreaterThanOrEqual(spec.min);
expect(v).toBeLessThanOrEqual(spec.max);
}
});
});
describe('toSol', () => {
it('converts lamports and degrades a bad input to zero rather than NaN', () => {
expect(toSol(SOL)).toBe(1);
expect(toSol('nope')).toBe(0);
});
});