Skip to content

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.

15.0 KB
Raw Blame
// Oracle conviction engine v2: unit tests.
//
// The engine is the product's brain, so its behavior is pinned here: the fitted
// model drives the score, probability maps to the public tier ladder through
// fixed anchors, the smart-money overlay adjusts in log-odds, and the one
// surviving hard cap (serial-rugger creator) ceilings the final score.

import { describe, it, expect } from 'vitest';
import {
	convict,
	evaluateModel,
	smartMoneyOverlay,
	scoreFromProbability,
	MODEL,
	PILLAR_WEIGHTS,
	WEIGHTS,
	tierTone,
} from '../../api/_lib/oracle/conviction.js';
import { archetypeFor, isProven, isFlagged } from '../../api/_lib/oracle/archetype.js';

// A launch whose raw signals sit in the model's empirically-best buckets
// (audit 2026-08-09: organic >=0.8 -> 59.7% good, 40+ unique buyers -> 80%,
// buy volume >=25 SOL -> 70.2%, snipe 0.1-0.3 -> 42.1%).
const strongLaunch = () => ({
	category: 'animal',
	launch: {
		organic_score: 0.85,
		bundle_score: 0.15,
		snipe_ratio: 0.2,
		coordination_score: 0.15,
		timing_entropy: 0.7,
		concentration_top1: 0.1,
		concentration_top10: 0.5,
		unique_buyers: 55,
		buy_sell_ratio: 2.5,
		buy_volume_sol: 30,
		largest_buy_sol: 6,
		avg_buy_sol: 0.6,
		dev_buy_sol: 0.3,
		mc_sol_first_seen: 29,
		dev_sold: false,
	},
	creator: { launches: 4, launchWins: 2 },
	smartMoney: { notable: [] },
});

// The empirically-worst buckets (organic <0.2 -> 1.3% good, no buyers, dead cap).
const deadLaunch = () => ({
	category: 'tech',
	launch: {
		organic_score: 0.1,
		bundle_score: 0.6,
		snipe_ratio: 0.8,
		coordination_score: 0.4,
		timing_entropy: 0.05,
		concentration_top1: 0.02,
		concentration_top10: 0.1,
		unique_buyers: 0,
		buy_volume_sol: 0.1,
		largest_buy_sol: 0.05,
		avg_buy_sol: 0.01,
		dev_buy_sol: 0,
		mc_sol_first_seen: 27,
		dev_sold: false,
	},
	creator: { launches: 0, launchWins: 0 },
	smartMoney: { notable: [] },
});

describe('model', () => {
	it('ships provenance: version, fit date, training size, base rate', () => {
		expect(MODEL.version).toBeGreaterThanOrEqual(3);
		expect(MODEL.training_rows).toBeGreaterThan(50_000);
		expect(MODEL.fitted_at).toBeTruthy();
		const head = MODEL.heads[MODEL.score_head];
		expect(head.base_rate).toBeGreaterThan(0);
		expect(head.base_rate).toBeLessThan(0.5);
		expect(Number.isFinite(head.intercept)).toBe(true);
	});

	it('scores the survivable-win head, not the bare spike', () => {
		// The whole point of v3. Ranking on `moon` alone counts a coin that ran 3x
		// and went to zero as a hit, which is how a high score ends up sitting on a
		// chart that is a cliff.
		expect(MODEL.score_head).toBe('win');
		for (const head of ['win', 'rug', 'moon']) {
			expect(MODEL.heads[head], `missing ${head} head`).toBeTruthy();
		}
	});

	it('every bucket weight carries its sample size and observed rates, per head', () => {
		for (const f of MODEL.features) {
			for (const [bucket, stats] of Object.entries(f.buckets)) {
				expect(stats.n, `${f.key} ${bucket} n`).toBeGreaterThan(0);
				for (const head of Object.keys(MODEL.heads)) {
					expect(Number.isFinite(stats.w?.[head]), `${f.key} ${bucket} w.${head}`).toBe(true);
					expect(stats.rate?.[head], `${f.key} ${bucket} rate.${head}`).toBeGreaterThanOrEqual(0);
					expect(stats.rate[head]).toBeLessThanOrEqual(1);
				}
			}
		}
	});

	it('names the features it dropped rather than silently omitting them', () => {
		// A signal that stopped arriving is an outage upstream, and the model is
		// where it becomes visible. Absence with no explanation hides that.
		for (const d of MODEL.dropped_features) {
			expect(typeof d.key).toBe('string');
			expect(d.share).toBeGreaterThan(0);
			expect(MODEL.features.some((f) => f.key === d.key)).toBe(false);
		}
	});

	it('derived pillar weights sum to 1', () => {
		const sum = Object.values(PILLAR_WEIGHTS).reduce((a, b) => a + b, 0);
		expect(sum).toBeCloseTo(1, 1);
		expect(WEIGHTS).toBe(PILLAR_WEIGHTS); // legacy alias
	});
});

describe('scoreFromProbability', () => {
	it('lands each tier boundary exactly on its probability anchor', () => {
		const a = MODEL.tier_probability_anchors;
		expect(scoreFromProbability(a.watch)).toBe(34);
		expect(scoreFromProbability(a.lean)).toBe(56);
		expect(scoreFromProbability(a.strong)).toBe(72);
		expect(scoreFromProbability(a.prime)).toBe(86);
	});

	it('is monotone and clamped', () => {
		expect(scoreFromProbability(0)).toBe(0);
		expect(scoreFromProbability(1)).toBe(100);
		expect(scoreFromProbability(-1)).toBe(0);
		expect(scoreFromProbability(2)).toBe(100);
		let prev = -1;
		for (let p = 0; p <= 1.0001; p += 0.01) {
			const s = scoreFromProbability(p);
			expect(s).toBeGreaterThanOrEqual(prev);
			prev = s;
		}
	});
});

describe('evaluateModel', () => {
	it('reads raw launch signals and produces a finite fused probability', () => {
		const out = evaluateModel(strongLaunch());
		expect(Number.isFinite(out.z)).toBe(true);
		expect(out.p).toBeGreaterThan(0);
		expect(out.p).toBeLessThan(1);
		expect(out.hits.length).toBe(MODEL.features.length);
	});

	it('scores strong evidence far above dead evidence', () => {
		const strong = evaluateModel(strongLaunch());
		const dead = evaluateModel(deadLaunch());
		expect(strong.p).toBeGreaterThan(dead.p * 5);
	});

	it('tolerates an empty intel without throwing or NaN', () => {
		const out = evaluateModel({});
		expect(Number.isFinite(out.p)).toBe(true);
	});

	it('falls back to derived CoinIntel fields when raw signals are absent', () => {
		const viaRaw = evaluateModel({ launch: { organic_score: 0.85 } });
		const viaDerived = evaluateModel({ structure: { organicScore: 85 } });
		// Same bucket hit either way.
		const rawHit = viaRaw.hits.find((h) => h.key === 'organic_score');
		const derivedHit = viaDerived.hits.find((h) => h.key === 'organic_score');
		expect(rawHit.bucket).toBe(derivedHit.bucket);
	});

	it('computes buy_sell_ratio from behavior counts when the raw signal is missing', () => {
		const out = evaluateModel({ behavior: { buyCount: 30, sellCount: 10 } });
		const hit = out.hits.find((h) => h.key === 'buy_sell_ratio');
		expect(hit.bucket).toBe('2-4');
	});
});

describe('smartMoneyOverlay', () => {
	it('stands down on smart money once the model fits it, instead of double-counting', () => {
		// v2 added up to +0.75 log-odds by hand because proven wallets were too
		// rare to fit. They are not any more: the model carries a fitted
		// smart_money_count feature, so the hand-tuned bump has to disappear or the
		// same wallets get counted twice.
		const out = smartMoneyOverlay({
			smartWalletCount: 3,
			provenBuyLamports: 5e9,
			totalBuyLamports: 1e10,
			notable: [{ wallet: 'a', label: 'smart_money', score: 88 }],
		});
		expect(MODEL.features.some((f) => f.key === 'smart_money_count')).toBe(true);
		expect(out.z).toBe(0);
		expect(out.suppressed).toContain('smart_money_count');
		expect(out.provenCount).toBe(3);
	});

	it('drags on flagged (rugger/dumper) wallets', () => {
		const out = smartMoneyOverlay({
			notable: [
				{ wallet: 'r', label: 'rugger', score: 10 },
				{ wallet: 'd', label: 'dumper', score: 20 },
			],
		});
		expect(out.z).toBeLessThan(0);
		expect(out.reasons.join(' ')).toMatch(/flagged/);
	});

	it('penalizes smart money already exiting', () => {
		const holding = smartMoneyOverlay({ provenBuyLamports: 1e10, provenSellLamports: 0 });
		const exiting = smartMoneyOverlay({ provenBuyLamports: 1e10, provenSellLamports: 6e9 });
		expect(exiting.z).toBeLessThan(holding.z);
	});

	it('caps a serial-rugger creator at 45', () => {
		const out = smartMoneyOverlay({}, { launches: 5, launchWins: 0 });
		// The CEILING is a product guarantee and survives; the log-odds nudge does
		// not, because creator_record is a fitted feature.
		expect(out.cap).toBe(45);
		expect(out.suppressed).toContain('creator_record');
		expect(out.reasons.join(' ')).toMatch(/rug pattern/);
	});

	it('a flagged creator label caps too', () => {
		const out = smartMoneyOverlay({}, { label: 'rugger', launches: 1, launchWins: 0 });
		expect(out.cap).toBe(45);
	});

	it('a dumping creator does not cap, and defers to the fitted creator feature', () => {
		const out = smartMoneyOverlay({}, { launches: 3, launchWins: 1, dumpRate: 0.7 });
		expect(out.cap).toBe(100);
		expect(out.z).toBe(0);
	});
});

describe('convict (fusion)', () => {
	it('a launch in the best-evidence buckets outranks a dead one by a wide margin', () => {
		// v3 is deliberately stricter than v2: it ranks P(runs AND holds), whose
		// base rate is 2.94%, so a fixture that used to clear 72 no longer has to.
		// What must hold is separation, which is what a ranking is for.
		const strong = convict(strongLaunch());
		const dead = convict(deadLaunch());
		expect(strong.score).toBeGreaterThan(dead.score + 20);
		expect(strong.probabilities.win).toBeGreaterThan(dead.probabilities.win * 5);
	});

	it('publishes upside, rug risk and give-back risk beside the score', () => {
		const v = convict(strongLaunch());
		for (const key of ['rugRisk', 'upside', 'giveBackRisk', 'survival']) {
			expect(v[key], key).toBeGreaterThanOrEqual(0);
			expect(v[key], key).toBeLessThanOrEqual(100);
		}
		expect(v.survival).toBe(100 - v.rugRisk);
		// give-back is 1 - win/moon, so it is only 0 when every run is kept.
		expect(v.giveBackRisk).toBe(
			Math.max(0, Math.min(100, Math.round((1 - Math.min(1, v.probabilities.win / v.probabilities.moon)) * 100))),
		);
	});

	it('separates a coin that runs from a coin that runs and keeps it', () => {
		// The failure v3 exists to prevent: high upside, nothing left afterwards.
		// Whatever the fixtures score, upside can never be below the survivable
		// win, because keeping a run requires having one.
		for (const fixture of [strongLaunch(), deadLaunch()]) {
			const v = convict(fixture);
			expect(v.probabilities.moon).toBeGreaterThanOrEqual(v.probabilities.win - 1e-9);
		}
	});

	it('a dead launch reads avoid/watch', () => {
		const v = convict(deadLaunch());
		expect(['avoid', 'watch']).toContain(v.tier);
	});

	it('a serial-rugger creator ceilings the FINAL score, never above watch', () => {
		const intel = strongLaunch();
		intel.creator = { launches: 6, launchWins: 0 };
		const v = convict(intel);
		expect(v.score).toBeLessThanOrEqual(45);
		expect(v.pedigreeCap).toBe(45);
		expect(v.badges).toContain('pedigree-flag');
		expect(v.badges).not.toContain('prime');
	});

	it('smart money lifts the fused score, by the amount the data supports', () => {
		const base = convict(strongLaunch());
		const withSm = strongLaunch();
		// Two or three proven wallets: 351 labeled launches, 55.0% survivable-win
		// rate, zero rugs. Comfortably the best-evidenced bucket in the model.
		withSm.launch = { ...withSm.launch, smart_money_count: 3 };
		withSm.smartMoney = {
			smartWalletCount: 3,
			provenBuyLamports: 5e9,
			totalBuyLamports: 1e10,
			notable: [{ wallet: 'a', label: 'smart_money', score: 88 }],
		};
		const v = convict(withSm);
		expect(v.probability).toBeGreaterThan(base.probability);
		expect(v.probabilities.rug).toBeLessThan(base.probabilities.rug);
		expect(v.badges).toContain('smart-money');
	});

	it('says almost nothing about a bucket it has almost no evidence for', () => {
		// Four or more proven wallets is 34 launches. Before weight shrinkage that
		// bucket fitted at -0.64 log-odds and actively reversed a verdict on the
		// strength of 34 rows; it now moves the score by a rounding error, which is
		// the honest amount to move it by.
		const base = convict(strongLaunch());
		const thin = strongLaunch();
		thin.launch = { ...thin.launch, smart_money_count: 6 };
		const v = convict(thin);
		expect(Math.abs(v.probability - base.probability)).toBeLessThan(0.05);
	});

	it('flagged wallets pull a coin down', () => {
		const clean = convict(strongLaunch());
		const dirty = strongLaunch();
		dirty.smartMoney = {
			notable: [
				{ wallet: 'r', label: 'rugger', score: 5 },
				{ wallet: 'd', label: 'dumper', score: 10 },
				{ wallet: 'e', label: 'rugger', score: 8 },
			],
		};
		// The strong fixture saturates the 0-100 score line, so assert on the
		// underlying probability, which is strictly monotone in the log-odds.
		expect(convict(dirty).probability).toBeLessThan(clean.probability);
	});

	it('score equals the probability mapped through the tier anchors (no cap case)', () => {
		const v = convict(strongLaunch());
		expect(v.score).toBe(scoreFromProbability(v.probability));
	});

	it('returns a transparent breakdown: pillars, reasons quoting observed rates, provenance', () => {
		const v = convict(strongLaunch());
		for (const k of ['pedigree', 'structure', 'narrative', 'momentum']) {
			expect(v.pillars[k]).toBeGreaterThanOrEqual(0);
			expect(v.pillars[k]).toBeLessThanOrEqual(100);
		}
		expect(v.reasons.length).toBeGreaterThan(0);
		expect(v.reasons.some((r) => /% of similar launches worked/.test(r.text))).toBe(true);
		expect(v.model.training_rows).toBe(MODEL.training_rows);
		expect(v.weights).toBe(PILLAR_WEIGHTS);
	});

	it('is deterministic: same input, same score', () => {
		const a = convict(strongLaunch());
		const b = convict(strongLaunch());
		expect(a.score).toBe(b.score);
		expect(a.probability).toBe(b.probability);
	});

	it('reports high confidence on fully-populated intel and low on an empty one', () => {
		const full = convict(strongLaunch());
		const empty = convict({});
		expect(full.confidence).toBeGreaterThan(empty.confidence);
		expect(empty.confidenceLabel).toBe('low');
		expect(empty.badges).toContain('thin-data');
	});

	it('an empty intel object does not throw and reads low', () => {
		const v = convict({});
		expect(v.score).toBeGreaterThanOrEqual(0);
		expect(v.score).toBeLessThanOrEqual(100);
		expect(['avoid', 'watch']).toContain(v.tier);
	});

	it('unknown pedigree no longer ceilings the verdict', () => {
		// v1's unknown-pedigree cap made Strong literally unreachable: across 202k
		// live scores it never once produced a score above 71. Missing wallet data
		// must cost a coin nothing but the evidence it did not supply, so no cap is
		// applied and the score still tracks the tape.
		const intel = strongLaunch();
		intel.creator = {};
		intel.smartMoney = {};
		const v = convict(intel);
		expect(v.pedigreeCap).toBe(100);
		expect(v.badges).not.toContain('pedigree-flag');
		expect(v.score).toBeGreaterThan(convict(deadLaunch()).score);
	});
});

describe('archetypes', () => {
	it('resolves known labels and tolerates unknowns', () => {
		expect(archetypeFor('smart_money').tone).toBe('good');
		expect(archetypeFor('rugger').tone).toBe('bad');
		expect(archetypeFor(null).label).toBe('unproven');
		expect(archetypeFor('garbage').label).toBe('unproven');
	});

	it('isProven / isFlagged match the pedigree rules', () => {
		expect(isProven('smart_money')).toBe(true);
		expect(isProven('kol')).toBe(true);
		expect(isProven('neutral', 80)).toBe(true);
		expect(isProven('neutral', 10)).toBe(false);
		expect(isFlagged('rugger')).toBe(true);
		expect(isFlagged('dumper')).toBe(true);
		expect(isFlagged('smart_money')).toBe(false);
	});
});

describe('tierTone', () => {
	it('maps tiers to UI tones', () => {
		expect(tierTone('prime')).toBe('good');
		expect(tierTone('strong')).toBe('good');
		expect(tierTone('lean')).toBe('warn');
		expect(tierTone('watch')).toBe('neutral');
		expect(tierTone('avoid')).toBe('bad');
	});
});