@keelage/mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keelage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @keelage/mcp
+
+Token intelligence for Robinhood Chain, as an MCP server. It reads a token from the chain itself, scores it against a published record of what happened next, and answers an agent in one call.
+
+Research only, not financial advice. Read-only: no wallet, no key, nothing here can spend.
+
+## Install
+
+Node 22 or newer. No runtime dependencies.
+
+```json
+{
+  "mcpServers": {
+    "keelage": { "command": "npx", "args": ["-y", "@keelage/mcp"] }
+  }
+}
+```
+
+Or from a checkout: `node core/bin/keelage.mjs` starts the stdio server.
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `keelage_scan` | The structural verdict for one token: verified source, launcher template, owner privileges, transfer-tax code, honeypot flags, sells clearing, holder concentration tier, ATH drawdown and 30-day-low band, entry test, size rule. Four states: `ELIGIBLE`, `NOT_ELIGIBLE`, `FAIL`, `UNVERIFIED`. |
+| `keelage_holders` | Top wallets with pools, contracts and burn addresses labeled; top-10 share excluding pools and contracts; burn share; share held by EIP-7702 smart accounts. |
+| `keelage_template` | Which launcher template the contract came from, with the template verdict, the ABI privileges and the transfer-tax identifier count. |
+| `keelage_record` | The dated studies, with sample sizes, behind every rule. |
+
+Rules, fixed: the score ranks, it never admits. Unknown facts cap size. Only evidence blocks. Unknown is `null`, never zero.
+
+### The `ruleset` argument
+
+`keelage_scan` takes an optional `ruleset`. The facts don't move; the lines the verdict policy reads can.
+
+- Omitted, or `"keelage-default"` (short form `"default"`): the 18 lines in `data/thresholds.json`, each with its origin, date and n, dated 2026-10-04. The only preset today.
+- `{ "lines": [{ "key": "pool.deep", "value": 100000 }] }`: keelage-default with those lines replaced. A key is one of the 18 below; a value is a number in that line's unit. An unknown key, a value of the wrong shape or a key given twice comes back as an `ok:false` result with the reason, never a verdict. One line can't be moved, `jev.halveBands`: the words on each band were measured at exactly those cuts.
+
+Every answer says what it ran under, in `verdict.ruleset`: `name` (`keelage-default`, or `custom` for your own lines), `date` (the preset's date, or today for your own lines) and `overrides` (the keys whose value differs from the default; empty for a preset).
+
+| Key | Unit | Default | What it decides |
+|---|---|---|---|
+| `top10.conviction` | % of supply | 30 | Conviction tier: the 10 largest wallets hold this much or less |
+| `top10.scout` | % of supply | 45 | Above this the token is watch-only and never sized |
+| `pool.deep` | USD in the pool | 50,000 | Conviction needs a pool at least this deep; thinner pools are scout size |
+| `size.cap.conviction` | USD | 1,000 | Largest size we would suggest for a conviction token |
+| `size.cap.scout` | USD | 100 | Largest size we would suggest for a scout token |
+| `size.poolShare` | % of the pool | 1 | Never more than this share of the pool, whatever the tier |
+| `deployer.max` | % of supply | 5 | A deployer still holding more than this fails the token |
+| `holders.min` | wallets | 100 | Fewer holders than this fails the entry test |
+| `entry.midPump` | % price change in 24h | 30 | Up more than this today fails the entry test |
+| `entry.minVolume24h` | USD traded in 24h | 10,000 | Quieter than this fails the entry test |
+| `entry.minTurnoverOfMcap` | % of market cap traded in 24h | 5 | Less turnover than this fails the entry test |
+| `entry.deepPoolTurnover` | % of the pool traded in 24h | 0.2 | A pool over $100,000 doing less than this reads as fabricated or dead |
+| `entry.convictionBelowPeak` | % below all-time high | 60 | Conviction needs at least this much decline from peak |
+| `liquidity.maxDrawdown` | % below its recorded peak | 70 | A pool drained more than this fails the token |
+| `base.atBase` | % above the 30-day low | 30 | At base band ends here |
+| `base.justOff` | % above the 30-day low | 100 | Just off base band ends here |
+| `base.wellOff` | % above the 30-day low | 500 | Well off base band ends here; beyond is already ran |
+| `jev.halveBands` | probability | 0.4, 0.5, 0.6, 0.7 | Bands for the halve-in-7-days read |
+
+A stricter preset ships only when every line it moves has a documented source: an earlier value stated in that line's own origin, or a dated study with its n. Today 1 line has one (`pool.deep` was 100,000 before 2026-08-01). The other 17 are set by hand or measured at their current value, and we don't invent the stricter number.
+
+## Hosted
+
+The same server runs at `https://mcp.keelage.ai/mcp` over Streamable HTTP (POST JSON-RPC; GET answers 405). No key and no sign-in. Per caller, 20 counted calls a day across `keelage_scan` and `keelage_holders`; `keelage_record` and `keelage_template` are never counted. The caller is the `X-Wallet` header when you send one (a 0x address), otherwise a salted hash of the network address that changes daily. Past the quota a priced tool answers with its price in USDG on Robinhood Chain and `x402.status: "not open yet"`; settlement opens when the merchant address is published. The hosted code is this package plus one transport file, so the two give the same answers.
+
+## Command line
+
+```
+keelage scan <0x> [--text] [--ruleset <name|json>]
+keelage holders <0x> [--no-smart]
+keelage template <0x>
+keelage record [study-key]
+keelage tools
+```
+
+## Environment (all optional)
+
+| Variable | Purpose |
+|---|---|
+| `ROBINHOOD_RPC_URL` | JSON-RPC endpoint. Default: the public Robinhood Chain RPC. |
+| `KEELAGE_STATE_DIR` | Cache directory. Default: `~/.cache/keelage`. |
+| `BLOCKSCOUT_IP` | Pin the explorer's A record where a resolver misdirects it. |
+| `CG_PRO_API_KEY` | CoinGecko Pro routing for GeckoTerminal reads. |
+| `TYPESAFE_API_KEY` | Jev probabilities as context on a verdict. |
+| `SOCIALDATA_API_KEY`, `XAI_API_KEY` | What X is saying, as context on a verdict. |
+
+## Upstreams
+
+DexScreener (pairs, takeover orders), Blockscout for Robinhood Chain (contract, source, ABI, holders), GoPlus (corroboration only), GeckoTerminal (price history, holder count), the chain RPC (`owner()`, `eth_getCode`).
+
+## Tests
+
+```
+npm test            # pure: measurements, verdict states, JSON shape, MCP handshake
+npm run test:live   # five reference tokens against the live chain
+```
+
+Research, timestamped.

package/bin/keelage.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// keelage - token intelligence for Robinhood Chain.
+//
+//   keelage                      stdio MCP server (what an agent client launches)
+//   keelage serve                same
+//   keelage scan <0x>  [--text] [--ruleset <name|json>]  verdict as JSON (or the text card)
+//   keelage holders <0x> [--no-smart]
+//   keelage template <0x>
+//   keelage record [study-key]
+//   keelage tools                the MCP tool list
+import { scanOne, renderScanText } from '../lib/gate.mjs';
+import { renderScanJson } from '../lib/render.mjs';
+import { holdersFor } from '../lib/holders.mjs';
+import { templateFor } from '../lib/template.mjs';
+import { trackRecord } from '../lib/record.mjs';
+import { serve, TOOLS } from '../server/mcp.mjs';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+// --ruleset takes a value: a preset name or a JSON object of overrides, as `--ruleset x` or `--ruleset=x`.
+let ruleset = 'default';
+const rest = [];
+for (let i = 1; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--ruleset') { ruleset = argv[++i]; if (ruleset === undefined) { console.error('usage: --ruleset <name|json>'); process.exit(2); } }
+  else if (a.startsWith('--ruleset=')) ruleset = a.slice('--ruleset='.length);
+  else rest.push(a);
+}
+if (typeof ruleset === 'string' && ruleset.trim().startsWith('{')) {
+  try { ruleset = JSON.parse(ruleset); } catch { console.error('--ruleset: not valid JSON'); process.exit(2); }
+}
+const flags = new Set(rest.filter((a) => a.startsWith('--')));
+const arg = rest.find((a) => !a.startsWith('--'));
+const out = (o) => process.stdout.write(JSON.stringify(o, null, 2) + '\n');
+const log = (...a) => console.error(...a);
+
+if (!cmd || cmd === 'serve') { serve(); }
+else if (cmd === 'scan') {
+  if (!arg) { log('usage: keelage scan <0x address> [--text] [--ruleset <name|json>]'); process.exit(2); }
+  const t0 = Date.now();
+  const res = await scanOne(arg, { log, ruleset });
+  if (flags.has('--text')) process.stdout.write(renderScanText(res) + '\n'); else out(renderScanJson(res));
+  log(`[keelage] scan ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+} else if (cmd === 'holders') {
+  if (!arg) { log('usage: keelage holders <0x address> [--no-smart]'); process.exit(2); }
+  out(await holdersFor(arg, { withSmartAccounts: !flags.has('--no-smart') }));
+} else if (cmd === 'template') {
+  if (!arg) { log('usage: keelage template <0x address>'); process.exit(2); }
+  out(await templateFor(arg));
+} else if (cmd === 'record') { out(trackRecord({ study: arg || null })); }
+else if (cmd === 'tools') { out(TOOLS); }
+else if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  process.stdout.write('keelage [serve] | scan <0x> [--text] [--ruleset <name|json>] | holders <0x> [--no-smart] | template <0x> | record [study] | tools\n');
+} else { log(`unknown command ${cmd}`); process.exit(2); }

package/data/thresholds.json

@@ -0,0 +1,26 @@
+{
+  "generatedAt": "2026-10-04",
+  "status": "hand-set",
+  "note": "Every line the rules use, with where it came from. Lines marked derived came out of a dated study on our own outcome rows. The others were set by hand and are stated as such until the nightly re-cut runs on our own store of outcome rows.",
+  "recut": { "cadence": "every 24 hours", "needs": "outcome rows with the raw facts at alert time (top-10 share, volume, market cap, distance from the 30-day low, drawdown from peak) flowing into Keelage's own store", "status": "not yet running" },
+  "lines": [
+    { "key": "top10.conviction", "value": 30, "unit": "% of supply", "usedFor": "Conviction tier: the 10 largest wallets hold this much or less", "origin": "A Midsummer Meme's Dream: Investigating Market Manipulations in the Meme Coin Ecosystem, arXiv 2507.01963 (posted 16 Apr 2025, revised 2 Jan 2026), section 5.1.3: the 10 largest holders owning over 30% of the supply was the most common anomaly, present in 87.14% of the anomalies detected among high-return tokens. Read July 2026. https://arxiv.org/abs/2507.01963", "setOn": "2026-07-23", "n": null, "derived": false },
+    { "key": "top10.scout", "value": 45, "unit": "% of supply", "usedFor": "Above this the token is watch-only and never sized", "origin": "Set by hand as a buffer above the 30% line", "setOn": "2026-07-23", "n": null, "derived": false },
+    { "key": "pool.deep", "value": 50000, "unit": "USD in the pool", "usedFor": "Conviction needs a pool at least this deep; thinner pools are scout size", "origin": "Set by hand, lowered from 100,000", "setOn": "2026-08-01", "n": null, "derived": false },
+    { "key": "size.cap.conviction", "value": 1000, "unit": "USD", "usedFor": "Largest size we would suggest for a conviction token", "origin": "Set by hand", "setOn": "2026-07-23", "n": null, "derived": false },
+    { "key": "size.cap.scout", "value": 100, "unit": "USD", "usedFor": "Largest size we would suggest for a scout token", "origin": "Set by hand", "setOn": "2026-07-23", "n": null, "derived": false },
+    { "key": "size.poolShare", "value": 1, "unit": "% of the pool", "usedFor": "Never more than this share of the pool, whatever the tier", "origin": "Set by hand", "setOn": "2026-07-23", "n": null, "derived": false },
+    { "key": "deployer.max", "value": 5, "unit": "% of supply", "usedFor": "A deployer still holding more than this fails the token", "origin": "Published research on token risk read in July 2026", "setOn": "2026-07-23", "n": null, "derived": false },
+    { "key": "holders.min", "value": 100, "unit": "wallets", "usedFor": "Fewer holders than this fails the entry test", "origin": "The one holder figure in the July 2026 research", "setOn": "2026-07-28", "n": null, "derived": false },
+    { "key": "entry.midPump", "value": 30, "unit": "% price change in 24h", "usedFor": "Up more than this today fails the entry test", "origin": "Set by hand", "setOn": "2026-07-28", "n": null, "derived": false },
+    { "key": "entry.minVolume24h", "value": 10000, "unit": "USD traded in 24h", "usedFor": "Quieter than this fails the entry test", "origin": "Board review: 105 passing tokens, 42 under this floor; 39 survived both floors", "setOn": "2026-09-22", "n": 105, "derived": true },
+    { "key": "entry.minTurnoverOfMcap", "value": 5, "unit": "% of market cap traded in 24h", "usedFor": "Less turnover than this fails the entry test", "origin": "Board review: median turnover of passing tokens was 4% of market cap", "setOn": "2026-09-22", "n": 105, "derived": true },
+    { "key": "entry.deepPoolTurnover", "value": 0.2, "unit": "% of the pool traded in 24h", "usedFor": "A pool over $100,000 doing less than this reads as fabricated or dead", "origin": "Set by hand", "setOn": "2026-07-28", "n": null, "derived": false },
+    { "key": "entry.convictionBelowPeak", "value": 60, "unit": "% below all-time high", "usedFor": "Conviction needs at least this much decline from peak", "origin": "Set by hand, replacing the base-proximity block", "setOn": "2026-09-09", "n": null, "derived": false },
+    { "key": "liquidity.maxDrawdown", "value": 70, "unit": "% below its recorded peak", "usedFor": "A pool drained more than this fails the token", "origin": "Set by hand", "setOn": "2026-09-09", "n": null, "derived": false },
+    { "key": "base.atBase", "value": 30, "unit": "% above the 30-day low", "usedFor": "At base band ends here", "origin": "First-alert study: within 30% of the low read +8% median, 61% positive", "setOn": "2026-09-04", "n": 1013, "derived": true },
+    { "key": "base.justOff", "value": 100, "unit": "% above the 30-day low", "usedFor": "Just off base band ends here", "origin": "First-alert study: 30 to 100% read -1% median, 50% positive", "setOn": "2026-09-04", "n": 1013, "derived": true },
+    { "key": "base.wellOff", "value": 500, "unit": "% above the 30-day low", "usedFor": "Well off base band ends here; beyond is already ran", "origin": "First-alert study: over 500% read -70% median, 13% positive, 31% down 80%+", "setOn": "2026-09-04", "n": 1013, "derived": true },
+    { "key": "jev.halveBands", "value": [0.4, 0.5, 0.6, 0.7], "unit": "probability", "usedFor": "Bands for the halve-in-7-days read", "origin": "Backtest of 423 alerts against realized 7-day return, rank correlation -0.47", "setOn": "2026-09-24", "n": 423, "derived": true }
+  ]
+}

package/data/track-record.json

@@ -0,0 +1,61 @@
+{
+  "title": "Track record",
+  "note": "Every figure carries its measurement date and sample size. Published as measured, including the uncomfortable rows.",
+  "operatingSince": { "hourlyRuns": "2026-07", "robinhoodChainOnly": "2026-09-09" },
+  "studies": [
+    {
+      "key": "gate-policy-review",
+      "date": "2026-09-04",
+      "title": "Gate policy review, 7-day outcomes on alert rows",
+      "findings": [
+        { "metric": "Rows that passed the base-entry gate, 7 days", "n": 27, "medianPct": 3.8, "positivePct": 63 },
+        { "metric": "Rows the gate blocked, 7 days", "n": 204, "medianPct": -29.6, "positivePct": 24 },
+        { "metric": "Rows that passed the base-entry gate, 24 hours", "n": 27, "medianPct": 0.1, "positivePct": 52 },
+        { "metric": "Rows the gate blocked, 24 hours", "n": 204, "medianPct": -11.1, "positivePct": 33 },
+        { "metric": "First alert, 30-day-low distance 30% or less", "n": 1013, "medianPct": 8, "positivePct": 61, "down80Pct": 0, "cohort": "subset of 1,013 first-alert rows" },
+        { "metric": "First alert, 30-day-low distance over 500%", "n": 1013, "medianPct": -70, "positivePct": 13, "down80Pct": 31, "cohort": "subset of 1,013 first-alert rows" },
+        { "metric": "Community takeover claim present", "n": 155, "medianPct": -58, "positivePct": 11 },
+        { "metric": "Community takeover claim absent", "n": 858, "medianPct": -13, "positivePct": 37 },
+        { "metric": "Third-party-score rules on Robinhood Chain, admitted", "n": 49, "medianPct": -25, "positivePct": 24 },
+        { "metric": "Third-party-score rules on Robinhood Chain, rejected", "n": 108, "medianPct": -2, "positivePct": 30 }
+      ]
+    },
+    {
+      "key": "template-census",
+      "date": "2026-09-09",
+      "title": "Launcher template census",
+      "findings": [
+        { "metric": "Robinhood Chain token contracts read", "n": 384 },
+        { "metric": "Verified source", "n": 384, "sharePct": 85 },
+        { "metric": "Deployed by a launcher factory", "n": 384, "sharePct": 92 },
+        { "metric": "Covered by the 5 registered templates", "n": 384, "sharePct": 68, "breakdown": { "pons-launcher": 141, "launchtoken": 61, "robinhood-stock": 34, "doppler": 32, "uerc20-pools-trade": 16 } }
+      ]
+    },
+    {
+      "key": "base-band-outcomes",
+      "date": "2026-09-22",
+      "title": "Robinhood-only era, alerts 7 days or older, by base band",
+      "caveat": "n between 10 and 30 per band. Small. Shown with that caveat.",
+      "findings": [
+        { "metric": "Already ran", "medianPct": 2.1, "reached2xPct": 37 },
+        { "metric": "Well off base", "medianPct": -51.8, "reached2xPct": 21 },
+        { "metric": "Just off base", "medianPct": -33.4, "reached2xPct": 6 },
+        { "metric": "At base", "medianPct": -77.4, "reached2xPct": 10 }
+      ]
+    },
+    {
+      "key": "jev-halve-calibration",
+      "date": "2026-09-24",
+      "title": "Jev halve-in-7-days probability against realized 7-day return",
+      "findings": [
+        { "metric": "Spearman, halve 7d vs realized return", "n": 423, "value": -0.47 },
+        { "metric": "Spearman, up 7d vs realized return", "n": 423, "value": 0.1 },
+        { "metric": "Band 0 to 0.4", "n": 29, "halvedPct": 0, "medianPct": -4 },
+        { "metric": "Band 0.4 to 0.5", "n": 67, "halvedPct": 1, "medianPct": -7 },
+        { "metric": "Band 0.5 to 0.6", "n": 171, "halvedPct": 32, "medianPct": -26 },
+        { "metric": "Band 0.6 to 0.7", "n": 120, "halvedPct": 52, "medianPct": -51 },
+        { "metric": "Band 0.7 to 1.0", "n": 36, "halvedPct": 83, "medianPct": -83 }
+      ]
+    }
+  ]
+}

package/lib/calc.mjs

@@ -0,0 +1,338 @@
+// calc.mjs - pure measurement functions over provider payloads. No network, no state.
+// Every numeric line comes from data/thresholds.json, which carries each line's origin, date and n.
+// A ruleset is that file resolved into a frozen object with its derived tables. The default is resolved
+// once at import; a preset (data/rulesets/<name>.json) or a set of overrides is resolved per call.
+import { io } from './io.mjs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+// A bundled runtime has no import.meta.url; paths then only serve as keys for the embedded store.
+const HERE = (() => { try { return dirname(fileURLToPath(import.meta.url)); } catch { return '/keelage/' + 'lib'; } })();
+const DATA = join(HERE, '..', 'data');
+const RULESETS_DIR = join(DATA, 'rulesets');
+export const THRESHOLDS = JSON.parse(io.read(join(DATA, 'thresholds.json')));
+
+// ---------- Rulesets ----------
+
+// A bad ruleset argument is a caller error with a message the caller can act on, never a crash.
+export class RulesetError extends Error { constructor(message) { super(message); this.name = 'RulesetError'; this.code = 'RULESET'; } }
+
+const RESOLVED = Symbol('keelage.ruleset');
+const PRESET_NAME = /^[a-z][a-z0-9-]{0,31}$/;
+// jev.halveBands is a calibration, not a policy line: each band carries the n, halved share and median
+// measured at exactly those cuts (jev.mjs), so moving the cuts would print figures measured elsewhere.
+const NOT_OVERRIDABLE = new Set(['jev.halveBands']);
+const todayUtc = () => new Date().toISOString().slice(0, 10);
+const deepFreeze = (o) => {
+  if (o && typeof o === 'object' && !Object.isFrozen(o) && !(o instanceof Set)) { Object.freeze(o); for (const v of Object.values(o)) deepFreeze(v); }
+  return o;
+};
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const sameShape = (ref, v) => Array.isArray(ref) ? Array.isArray(v) && v.length === ref.length && v.every(isNum) : isNum(v);
+const show = (v) => JSON.stringify(v);
+
+// Preset names on disk, without the default. An absent directory means no presets.
+export function presetNames() {
+  try { return io.list(RULESETS_DIR).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).filter((n) => PRESET_NAME.test(n)).sort(); } catch { return []; }
+}
+// The default's public name is "keelage-default" (what the site and every verdict print); "default" is its short form.
+export const DEFAULT_NAME = 'keelage-default';
+const isDefaultName = (s) => s === 'default' || s === DEFAULT_NAME;
+export const knownRulesets = () => [DEFAULT_NAME, ...presetNames()];
+
+// The tables every rule reads, computed from one set of lines. `label` names the source in a miss.
+function tablesFrom(lines, label) {
+  const values = Object.fromEntries(lines.map((l) => [l.key, l.value]));
+  const line = (key) => { if (!(key in values)) throw new Error(`${label} has no line ${key}`); return values[key]; };
+  // Concentration is a sizing TIER, never a gate. The deep-liquidity bar only decides whether a
+  // well-distributed token is capped at scout size; the 1%-of-pool rule throttles it independently.
+  const TIER_BARS = { conviction: line('top10.conviction'), scout: line('top10.scout'), deepLiqUsd: line('pool.deep') };
+  // Tier names are constants. The scout label embeds the liquidity bar, and that exact string is also a
+  // key in ACTIONABLE_TIERS and TIER_CAP, so it is derived once and never typed out.
+  const TIERS = {
+    CONVICTION: 'CONVICTION',
+    SCOUT_DIST_OK: `scout (dist ok, liq under ${Math.round(TIER_BARS.deepLiqUsd / 1000)}k)`,
+    SCOUT_CLUSTER: 'scout + cluster-check',
+    WATCH_ONLY: 'watch-only',
+    DIST_UNKNOWN: 'distribution-unknown',
+  };
+  // Size caps per tier, in USD. Keyed off TIERS so the scout label can never go stale here.
+  const TIER_CAP = {
+    [TIERS.CONVICTION]: line('size.cap.conviction'),
+    [TIERS.SCOUT_CLUSTER]: line('size.cap.scout'),
+    [TIERS.SCOUT_DIST_OK]: line('size.cap.scout'),
+  };
+  // The only tiers that may be presented as entry-eligible. A whitelist: a tier added later is non-actionable
+  // until deliberately admitted here.
+  const ACTIONABLE_TIERS = new Set([TIERS.CONVICTION, TIERS.SCOUT_CLUSTER, TIERS.SCOUT_DIST_OK]);
+  // What predicted 7-day outcome over 1,013 first-alert rows, in order of strength: distance above the
+  // 30-day low (<=30%: +8% median, 61% positive; >500%: -70%, 13%), then market-cap band (<$500k -38%
+  // median vs $2M+ -1%). The score never predicted outcome, so it is the LAST tiebreak. Ranking orders
+  // what is shown; it admits nothing and blocks nothing.
+  const BASE_BANDS = [
+    { max: line('base.atBase'), key: 0, label: 'AT BASE' },
+    { max: line('base.justOff'), key: 1, label: 'just off base' },
+    { max: line('base.wellOff'), key: 2, label: 'well off base' },
+    { max: Infinity, key: 3, label: 'ALREADY RAN' },
+  ];
+  return { values, line, TIER_BARS, TIERS, TIER_CAP, ACTIONABLE_TIERS, BASE_BANDS };
+}
+
+function buildRuleset({ name, date, overrides, lines, label }) {
+  const rs = {
+    name, date, overrides, lines,
+    handSetLines: lines.filter((l) => !l.derived).length, derivedLines: lines.filter((l) => l.derived).length,
+    ...tablesFrom(lines, label),
+    [RESOLVED]: true,
+  };
+  return deepFreeze(rs);
+}
+
+export const DEFAULT_RULESET = buildRuleset({ name: DEFAULT_NAME, date: THRESHOLDS.generatedAt, overrides: [], lines: THRESHOLDS.lines, label: 'thresholds.json' });
+const defaultLine = (key) => DEFAULT_RULESET.lines.find((l) => l.key === key);
+
+const presetCache = new Map();
+function presetRuleset(name) {
+  if (!PRESET_NAME.test(name) || !presetNames().includes(name)) throw new RulesetError(`unknown ruleset "${name}" - known rulesets: ${knownRulesets().join(', ')} ("default" is short for ${DEFAULT_NAME})`);
+  if (presetCache.has(name)) return presetCache.get(name);
+  const file = JSON.parse(io.read(join(RULESETS_DIR, `${name}.json`)));
+  const given = new Map((file.lines || []).map((l) => [l.key, l]));
+  for (const key of given.keys()) if (!defaultLine(key)) throw new RulesetError(`ruleset "${name}" has a line thresholds.json does not: ${key}`);
+  // A preset states every line it changes; a line it leaves out inherits the default unchanged.
+  const lines = DEFAULT_RULESET.lines.map((l) => given.get(l.key) || l);
+  const rs = buildRuleset({ name, date: file.generatedAt || THRESHOLDS.generatedAt, overrides: [], lines, label: `ruleset ${name}` });
+  presetCache.set(name, rs);
+  return rs;
+}
+
+function overrideRuleset(spec) {
+  const list = spec.lines;
+  if (!Array.isArray(list) || !list.length) throw new RulesetError('ruleset overrides need lines: [{ key, value }], at least one');
+  const seen = new Map();
+  for (const o of list) {
+    const key = o && typeof o === 'object' ? o.key : undefined;
+    if (typeof key !== 'string') throw new RulesetError(`ruleset override ${show(o)} has no key`);
+    const ref = defaultLine(key);
+    if (!ref) throw new RulesetError(`unknown ruleset line "${key}" - known lines: ${DEFAULT_RULESET.lines.map((l) => l.key).join(', ')}`);
+    if (NOT_OVERRIDABLE.has(key)) throw new RulesetError(`ruleset line "${key}" is a calibration with its own n and cannot be overridden`);
+    if (seen.has(key)) throw new RulesetError(`ruleset line "${key}" is given twice`);
+    if (!sameShape(ref.value, o.value)) throw new RulesetError(`ruleset line "${key}" wants ${Array.isArray(ref.value) ? `${ref.value.length} numbers` : 'a number'} (${ref.unit}), got ${show(o.value)}`);
+    seen.set(key, o.value);
+  }
+  // Only a line whose value differs is an override. Nothing different means the default itself.
+  for (const [key, value] of [...seen]) if (show(value) === show(defaultLine(key).value)) seen.delete(key);
+  if (!seen.size) return DEFAULT_RULESET;
+  const date = todayUtc();
+  const lines = DEFAULT_RULESET.lines.map((l) => seen.has(l.key)
+    ? { ...l, value: seen.get(l.key), origin: `Override passed with the call, replacing ${show(l.value)}`, setOn: date, n: null, derived: false }
+    : l);
+  return buildRuleset({ name: 'custom', date, overrides: [...seen.keys()], lines, label: 'ruleset custom' });
+}
+
+// "keelage-default" (or "default"), a preset name, { lines: [{ key, value }] }, or an already resolved ruleset -> a frozen ruleset.
+export function resolveRuleset(spec = 'default') {
+  if (spec === undefined || spec === null || isDefaultName(spec)) return DEFAULT_RULESET;
+  if (spec && typeof spec === 'object' && spec[RESOLVED]) return spec;
+  if (typeof spec === 'string') return presetRuleset(spec);
+  if (spec && typeof spec === 'object' && !Array.isArray(spec)) return overrideRuleset(spec);
+  throw new RulesetError(`ruleset must be "${DEFAULT_NAME}", a preset name, or { lines: [{ key, value }] }, got ${show(spec)}`);
+}
+// The ruleset a candidate was scanned under; a candidate built without one reads the default.
+export const rulesetOf = (c) => (c?.ruleset && c.ruleset[RESOLVED] ? c.ruleset : DEFAULT_RULESET);
+
+// Module-level views of the default, kept for every caller that reads thresholds without a ruleset in hand.
+export const line = (key) => { if (!(key in DEFAULT_RULESET.values)) throw new Error(`thresholds.json has no line ${key}`); return DEFAULT_RULESET.values[key]; };
+//
+// Everything here MEASURES. The pass rule that consumes these measurements lives in gate.mjs.
+// Keeping the maths separate means every number the verdict rests on can be unit-tested against a
+// saved payload without touching a provider.
+
+// ---------- GoPlus token_security record ----------
+
+// GoPlus has no real record for this token: blank honeypot AND no holders AND no LP supply.
+// That shape is "provider has no data", never a structural fail. GoPlus also indexes Robinhood Chain
+// lazily: the first single-address call can return an empty result and a call seconds later returns
+// the record, so the caller re-asks once before giving up.
+export function goplusUnindexed(r) {
+  if (!r) return true;
+  const hp = r.is_honeypot === undefined || r.is_honeypot === null || r.is_honeypot === '';
+  const noHolders = !(r.holders || []).length;
+  const noLp = !r.lp_total_supply || Number(r.lp_total_supply) === 0;
+  return hp && noHolders && noLp;
+}
+
+// Top-10 from a GoPlus holders list with the pool and pair addresses removed. A pool is liquidity,
+// not a holder: counting it measured liquidity depth instead of concentration. The uncorrected figure
+// is kept alongside so the correction is auditable and a provider change is visible rather than silent.
+export function evmTop10(r) {
+  const holders = r?.holders || [];
+  const lpAddrs = new Set([
+    ...(r?.lp_holders || []).map((h) => String(h.address || '').toLowerCase()),
+    ...(r?.dex || []).map((x) => String(x.pair || '').toLowerCase()),
+  ].filter(Boolean));
+  const isPool = (h) => lpAddrs.has(String(h.address || '').toLowerCase());
+  const nonPool = holders.filter((h) => !isPool(h));
+  const sum = (list) => +list.slice(0, 10).reduce((a, h) => a + Number(h.percent || 0) * 100, 0).toFixed(1);
+  return {
+    // Absent holder data reads as UNKNOWN, never as perfect distribution.
+    top10Pct: holders.length ? sum(nonPool) : null,
+    top10RawPct: holders.length ? sum(holders) : null,
+    poolAcctsInTop10: holders.slice(0, 10).filter(isPool).length,
+  };
+}
+
+// Pool type from GoPlus. 'cl' = concentrated liquidity (Uniswap V3/V4 NFT positions, where lock/burn
+// is undefined), 'v2' = fungible LP tokens (lock/burn measurable), 'unknown' = no dex entries at all.
+export function lpModeOf(r) {
+  const types = (r?.dex || []).map((d) => String(d.liquidity_type || ''));
+  const nft = (r?.lp_holders || []).some((h) => Array.isArray(h.NFT_list) && h.NFT_list.length);
+  if (nft || types.some((t) => /v3|v4|cl|concentrated/i.test(t))) return 'cl';
+  if (types.some((t) => /v2/i.test(t))) return 'v2';
+  return types.length ? 'other' : 'unknown';
+}
+
+// LP-holder statistics. creatorLpPct = share of LP positions held by the creator or an un-renounced
+// owner: "the deployer is the pool" is the concentrated-liquidity form of "the deployer can pull the pool".
+export function lpStats(r) {
+  const lp = r?.lp_holders || [];
+  const real = lp.filter((h) => Number(h.percent || 0) > 0);
+  const zero = '0x0000000000000000000000000000000000000000';
+  const insiders = new Set([r?.creator_address, r?.owner_address].map((a) => String(a || '').toLowerCase()).filter((a) => a && a !== zero));
+  const pct = (h) => Number(h.percent || 0) * 100;
+  return {
+    lpHolders: real.length,
+    topLpPct: +Math.max(0, ...real.map(pct)).toFixed(1),
+    creatorLpPct: +real.filter((h) => insiders.has(String(h.address || '').toLowerCase())).reduce((s, h) => s + pct(h), 0).toFixed(1),
+    lockedOrBurned: lp.some((h) => (h.is_locked === 1 || /dead|null|burn/i.test(h.address || '')) && Number(h.percent || 0) > 0.9),
+    lpTotal: r?.lp_total_supply === undefined || r?.lp_total_supply === null || r?.lp_total_supply === '' ? null : Number(r.lp_total_supply),
+  };
+}
+
+// ---------- Blockscout holders page ----------
+
+// Top-10 from a Blockscout /tokens/{addr}/holders page with pool and contract addresses removed.
+// `supply` is the raw total_supply from /tokens/{addr}. A V4 pool sits inside one PoolManager singleton
+// and shows as a contract, so contracts are counted and reported rather than silently dropped.
+// Unknown supply or an empty page -> null, never 0.
+export function blockscoutTop10(items, poolAddrs, supply) {
+  const it = Array.isArray(items) ? items : [];
+  const sup = Number(supply || 0);
+  if (!it.length || !sup) return { top10Pct: null, top10InclPct: null, maxSinglePct: null, contractsInTop10: null, poolsInTop10: null };
+  const pools = new Set((poolAddrs || []).filter(Boolean).map((a) => String(a).toLowerCase()));
+  let incl = 0, ex = 0, max = 0, contracts = 0, poolsSeen = 0;
+  for (const h of it.slice(0, 10)) {
+    const v = (Number(h.value || 0) / sup) * 100;
+    const isPool = pools.has(String(h.address?.hash || '').toLowerCase());
+    const isContract = !!h.address?.is_contract;
+    incl += v;
+    if (isPool) poolsSeen++;
+    if (isContract) contracts++;
+    if (isPool || isContract) continue;
+    ex += v; if (v > max) max = v;
+  }
+  return { top10Pct: +ex.toFixed(1), top10InclPct: +incl.toFixed(1), maxSinglePct: +max.toFixed(1), contractsInTop10: contracts, poolsInTop10: poolsSeen };
+}
+
+// ---------- Contract structure from the ABI and verified source ----------
+
+// Owner privileges from ABI function names. A function's presence is the fact; whether the owner has
+// renounced is a separate on-chain read. Deterministic, no regex over prose.
+export const ABI_PRIVILEGES = {
+  owner: /^(owner|getOwner)$/i, mint: /^(mint|mintTo|mintFor)$/i, pause: /^(pause|unpause|setPaused)$/i,
+  blacklist: /blacklist|blocklist|denylist|setBot|isBot|antiBot/i, feeSetter: /^(set|update)(Fee|Fees|Tax|Taxes|BuyTax|SellTax|TransferTax)/i,
+  tradingToggle: /^(enableTrading|openTrading|setTradingEnabled|startTrading)$/i, upgrade: /^(upgradeTo|upgradeToAndCall)$/i,
+  maxLimits: /^(set|update)(MaxTx|MaxWallet|MaxTransaction)/i, // setters only - maxTxAmount / maxWalletBps getters are launch constants
+};
+export function abiPrivileges(fnNames) {
+  const fns = Array.isArray(fnNames) ? fnNames : [];
+  const out = Object.fromEntries(Object.entries(ABI_PRIVILEGES).map(([k, re]) => [k, fns.some((f) => re.test(String(f)))]));
+  // A live privilege can change what holders are able to do. `owner` alone (no setter) and anti-whale limits cannot.
+  out.live = out.mint || out.pause || out.blacklist || out.feeSetter || out.tradingToggle || out.upgrade;
+  return out;
+}
+
+// Transfer-tax markers in verified source. The identifiers are tax-specific on purpose: a bare /fee/
+// matches Uniswap `poolFee` reads (every launcher token) and ERC404 mint-fee errors. A template can
+// declare feeModel 'uniswap-pool-fee' to say its fee words are pool-tier reads.
+export const TAX_RE = /\b(_?(buy|sell|transfer|marketing|liquidity|dev|team|treasury|burn|reflection)(Tax|Fee|Fees|Taxes)\w*|_?tax(Fee|Wallet|Rate|Percent|Amount)\w*|excludeFromFee\w*|_?isExcludedFromFee\w*|swapBack\w*|swapAndLiquify\w*|feeWallet\w*|feeReceiver\w*|taxWallet\w*|_taxFee|_liquidityFee|totalFees?)\b/g;
+export const REFLECT_RE = /\b(ReflectionToken|_rTotal|tokenFromReflection|reflectionFromToken|_getRate)\b/g;
+export function taxCodeScan(src) {
+  const text = String(src || '');
+  const taxHits = (text.match(TAX_RE) || []).length, reflectHits = (text.match(REFLECT_RE) || []).length;
+  return { taxHits, reflectHits, taxCode: taxHits > 0 || reflectHits > 0 };
+}
+
+// Template lookup against templates.json. Match order: implementation name (proxies) -> creator
+// address -> contract name. An unregistered template is judged by ABI and source alone.
+export function resolveTemplate(registry, facts) {
+  const tpls = registry?.templates || [];
+  const lc = (x) => String(x || '').toLowerCase();
+  const creator = lc(facts?.creator), name = String(facts?.contractName || ''), impl = String(facts?.implName || '');
+  const excludeImpl = (registry?.excludeImplNames || []).includes(impl);
+  if (excludeImpl) return { key: 'excluded-implementation', verdict: 'exclude', note: `implementation ${impl}` };
+  for (const t of tpls) {
+    const m = t.match || {};
+    if (impl && (m.implNames || []).includes(impl)) return { key: t.key, verdict: t.verdict, feeModel: t.feeModel || null, note: t.note || null, by: 'impl' };
+  }
+  for (const t of tpls) {
+    const m = t.match || {};
+    if (creator && (m.creators || []).map(lc).includes(creator)) return { key: t.key, verdict: t.verdict, feeModel: t.feeModel || null, note: t.note || null, by: 'creator' };
+  }
+  for (const t of tpls) {
+    const m = t.match || {};
+    if (name && (m.contractNames || []).includes(name)) return { key: t.key, verdict: t.verdict, feeModel: t.feeModel || null, note: t.note || null, by: 'name' };
+  }
+  return { key: 'unregistered', verdict: 'unregistered', feeModel: null, note: name || impl || null, by: null };
+}
+
+// Liquidity drawdown from a history of [[day, liqUsd], ...] points against the current liquidity.
+// null until there are at least 3 points: a new token has no history to judge. A pool pulled or
+// drained shows here, where a V3/V4 lock flag cannot exist.
+export function liqDrawdown(liqHist, liqNow) {
+  const pts = (Array.isArray(liqHist) ? liqHist : []).map((p) => Number(p?.[1])).filter((n) => Number.isFinite(n) && n > 0);
+  if (pts.length < 3 || !Number.isFinite(+liqNow)) return { liqDropPct: null, liqPeak: pts.length ? Math.max(...pts) : null, points: pts.length };
+  const peak = Math.max(...pts);
+  return { liqDropPct: +Math.max(0, (1 - +liqNow / peak) * 100).toFixed(1), liqPeak: peak, points: pts.length };
+}
+
+// ---------- Sizing tier ----------
+// The default's tables, as module constants. The tables themselves are built in tablesFrom() above, once
+// per ruleset; these are the default ruleset's and are what every caller without a ruleset reads.
+export const TIER_BARS = DEFAULT_RULESET.TIER_BARS;
+export const TIERS = DEFAULT_RULESET.TIERS;
+export const TIER_CAP = DEFAULT_RULESET.TIER_CAP;
+
+export function tierFromTop10(top10Pct, liqUsd, rs = DEFAULT_RULESET) {
+  const { TIERS: T, TIER_BARS: B } = rs;
+  // Unknown distribution is its own tier and is not actionable.
+  if (top10Pct === null || top10Pct === undefined) return T.DIST_UNKNOWN;
+  if (top10Pct <= B.conviction) {
+    return (liqUsd || 0) >= B.deepLiqUsd ? T.CONVICTION : T.SCOUT_DIST_OK;
+  }
+  if (top10Pct <= B.scout) return T.SCOUT_CLUSTER;
+  return T.WATCH_ONLY;
+}
+
+// ---------- Ranking ----------
+// The base bands and what they predicted are described at tablesFrom(). Ranking orders what is shown;
+// it admits nothing and blocks nothing.
+export const BASE_BANDS = DEFAULT_RULESET.BASE_BANDS;
+export function baseBand(distPct, rs = DEFAULT_RULESET) {
+  if (distPct === null || distPct === undefined || !Number.isFinite(+distPct)) return { key: 4, label: 'base unknown' };
+  const d = +distPct;
+  return rs.BASE_BANDS.find((b) => d <= b.max);
+}
+export function mcapBand(mcapUsd) {
+  const m = +mcapUsd || 0;
+  if (m >= 2_000_000) return 0;
+  if (m >= 500_000) return 1;
+  return 2;
+}
+export function rankKey(c) {
+  const dist = c.baseEntry?.distPct ?? c.distFromLow30Pct ?? null;
+  return [baseBand(dist, rulesetOf(c)).key, mcapBand(c.mcapUsd), -(c.score || 0)];
+}
+export function rankCompare(a, b) {
+  const ka = rankKey(a), kb = rankKey(b);
+  for (let i = 0; i < ka.length; i++) if (ka[i] !== kb[i]) return ka[i] - kb[i];
+  return 0;
+}