@senpi/runtime 3.0.146 → 3.0.149

package/dist/quant/registry.js

@@ -0,0 +1,248 @@
+/**
+ * The quant run registry: every desk this runtime computed, under `<senpi-state>/quant/`.
+ *
+ *   runs/<runId>.json   one {@link QuantRunRecord} per run (document + meta)
+ *   index.json          newest-first summaries; the source for list, freshness and pruning
+ *
+ * Producer = owner (spec D3): the engine's document lives where the runtime can read it in-process
+ * for the widget. Writes are temp-then-rename; index read-modify-writes are serialized by a
+ * KeyedMutex. The single-flight slot is NOT here — it is in-memory in job.ts, so a crash can never
+ * wedge a wallet; a restart instead stamps leftover `running` rows failed (`markInterrupted`).
+ */
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { KeyedMutex } from "../utils/keyed-mutex.js";
+import { QUANT_DOC_VERSION, QUANT_RUN_ID_RE, QuantRunLookupError, quantError, quantRequestKey, quantRunArgs, } from "./types.js";
+/** Runs retained; older ones are deleted with their files. Running runs are never pruned. */
+export const QUANT_KEEP_RUNS = 20;
+/** A done run for the same request younger than this is served instead of recomputed. */
+export const QUANT_FRESH_MS = 10 * 60_000;
+const INDEX_FILE = "index.json";
+const RUNS_DIR = "runs";
+const INDEX_LOCK = "index";
+/** Per-run lock key prefix for {@link QuantRunRegistry.finish}; distinct from {@link INDEX_LOCK}. */
+const RUN_LOCK_PREFIX = "run:";
+/** Temp file then rename: a reader sees the old file or the new one, never half of either. */
+async function writeJsonAtomic(path, data) {
+    const tmp = `${path}.tmp.${process.pid}.${randomBytes(3).toString("hex")}`;
+    await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    await rename(tmp, path);
+}
+/**
+ * Project a record onto its index row. The row copies `whose` from meta so list surfaces can print
+ * the voice without opening every record, and carries the freshness `key` so `findFresh` never does.
+ */
+function summaryOf(record) {
+    const m = record.meta;
+    return {
+        runId: record.runId,
+        key: quantRequestKey(m),
+        addresses: m.addresses,
+        days: m.days,
+        whose: m.whose,
+        book: m.book,
+        status: m.status,
+        startedAt: m.startedAt,
+        ...(m.finishedAt ? { finishedAt: m.finishedAt } : {}),
+    };
+}
+/** File-backed registry of quant runs. See the module doc for the layout and invariants. */
+export class QuantRunRegistry {
+    opts;
+    mutex = new KeyedMutex();
+    keep;
+    freshMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.keep = opts.keep ?? QUANT_KEEP_RUNS;
+        this.freshMs = opts.freshMs ?? QUANT_FRESH_MS;
+    }
+    /** A fresh run id (`qd-` + 8 hex). */
+    newRunId() {
+        return `qd-${randomBytes(4).toString("hex")}`;
+    }
+    /** The record path for a VALID run id. Throws on anything else, so no caller can build a traversal. */
+    runPath(runId) {
+        if (!QUANT_RUN_ID_RE.test(runId))
+            throw new Error(`not a quant run id: ${JSON.stringify(runId)}`);
+        return join(this.opts.dir, RUNS_DIR, `${runId}.json`);
+    }
+    /** Record a new `running` run and put it at the head of the index. */
+    async create(runId, request, engineVersion) {
+        const record = {
+            runId,
+            docVersion: QUANT_DOC_VERSION,
+            meta: {
+                ...request,
+                addresses: request.addresses.map((a) => a.toLowerCase()),
+                startedAt: new Date(this.opts.now()).toISOString(),
+                engineVersion,
+                status: "running",
+            },
+        };
+        await mkdir(join(this.opts.dir, RUNS_DIR), { recursive: true });
+        await writeJsonAtomic(this.runPath(runId), record);
+        await this.updateIndex((runs) => [summaryOf(record), ...runs.filter((r) => r.runId !== runId)]);
+        return record;
+    }
+    /**
+     * Close a run with its outcome. The FIRST outcome wins: a record that is already terminal
+     * (done/failed/refused) is never overwritten, and the call answers the stored record instead.
+     *
+     * Why first-wins: two finishers can race on one run — the engine's exit landing just as its
+     * watchdog fires, or the boot janitor meeting a run whose file was written done a moment before a
+     * crash cut off the index update. Overwriting would turn a delivered desk into a failure. The
+     * check-then-write is serialized under a per-run lock (`run:<id>`, never the index lock; nothing
+     * nests on it), so the second finisher always sees the first one's file.
+     *
+     * @returns The stored record after the call — the new one, or the earlier terminal one untouched.
+     * @throws When the run has no record (it was never created, or its file is gone or unreadable).
+     */
+    async finish(runId, outcome) {
+        const settled = await this.settle(runId, outcome);
+        if (!settled)
+            throw new Error(`quant run ${runId} has no record to finish`);
+        return settled.record;
+    }
+    /**
+     * The body of {@link finish}, reporting whether it wrote. `undefined` = no readable record.
+     *
+     * When the record is already terminal it re-syncs that run's index row from the file rather than
+     * writing: the file is the truth, and an index row still saying `running` (the crash window) would
+     * otherwise make `status` report a dead run as live. For a double finish that already updated the
+     * index, the re-sync rewrites the same row — harmless.
+     */
+    async settle(runId, outcome) {
+        return this.mutex.withKeyLock(`${RUN_LOCK_PREFIX}${runId}`, async () => {
+            const current = await this.readRecord(runId);
+            if (!current?.meta)
+                return undefined;
+            if (current.meta.status !== "running") {
+                await this.updateIndex((runs) => runs.map((r) => (r.runId === runId ? summaryOf(current) : r)));
+                return { record: current, wrote: false };
+            }
+            const next = {
+                runId: current.runId,
+                docVersion: current.docVersion,
+                meta: { ...current.meta, status: outcome.status, finishedAt: new Date(this.opts.now()).toISOString() },
+                ...(outcome.status === "done" ? { document: outcome.document } : { error: outcome.error }),
+            };
+            await writeJsonAtomic(this.runPath(runId), next);
+            await this.updateIndex((runs) => runs.map((r) => (r.runId === runId ? summaryOf(next) : r)));
+            return { record: next, wrote: true };
+        });
+    }
+    /**
+     * Read a run. `undefined` for an invalid id, a missing file or an unreadable one — all three are
+     * "no such run" to a caller. Throws {@link QuantRunLookupError} for a record of another docVersion.
+     */
+    async get(runId) {
+        if (!QUANT_RUN_ID_RE.test(runId))
+            return undefined;
+        const record = await this.readRecord(runId);
+        if (!record)
+            return undefined;
+        if (record.docVersion !== QUANT_DOC_VERSION) {
+            const again = record.meta?.addresses ? quantRunArgs(record.meta) : "<0x address>";
+            throw new QuantRunLookupError(quantError("E_QUANT_DOC_VERSION", `run ${runId} was stored as docVersion ${String(record.docVersion)}; this runtime reads docVersion ${QUANT_DOC_VERSION} only.`, `Run the desk again: openclaw senpi quant run ${again} --fresh`));
+        }
+        return record;
+    }
+    /**
+     * Newest-first summaries. The index is already bounded by {@link updateIndex}'s pruning: at most
+     * `keep` rows plus any `running` rows past the cap. It is deliberately NOT sliced to `keep` here —
+     * pruning spares a running run precisely so it stays visible, and a slice would hide a live run
+     * from `senpi quant list` while its record still exists.
+     */
+    async list() {
+        return (await this.readIndex()).runs;
+    }
+    /** The newest done run for this exact request finished within the freshness window, if any. */
+    async findFresh(request) {
+        const key = quantRequestKey(request);
+        const hit = (await this.readIndex()).runs.find((r) => r.key === key && r.status === "done");
+        if (!hit?.finishedAt || this.opts.now() - Date.parse(hit.finishedAt) >= this.freshMs)
+            return undefined;
+        try {
+            const record = await this.get(hit.runId);
+            return record?.meta.status === "done" && record.document ? record : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Boot janitor: every run still `running` in the index belongs to a process that no longer exists
+     * (the slot is in-memory only). Each such row is resolved from its file:
+     * - file still `running` → stamped `failed` with the exact re-run command, so `senpi quant status`
+     *   never reports a dead run as live;
+     * - file already terminal (the process died between writing the record and the index) → the
+     *   index row is re-synced from the file; the delivered outcome is kept, never stamped failed;
+     * - no readable file → the row is dropped (there is nothing to report or re-read).
+     *
+     * Must run before this process starts any run of its own: a run it created would be `running`
+     * too and would be stamped. The job controller gates `start` on it for that reason.
+     *
+     * @returns Only the ids it STAMPED failed — not re-synced or dropped rows — so the boot log names
+     *          exactly the runs a restart cut short.
+     */
+    async markInterrupted() {
+        const stamped = [];
+        for (const s of (await this.readIndex()).runs) {
+            if (s.status !== "running")
+                continue;
+            const error = quantError("E_QUANT_ENGINE_ERROR", `run ${s.runId} was interrupted by a gateway restart before it finished.`, `Run the desk again: openclaw senpi quant run ${quantRunArgs(s)}`);
+            const settled = await this.settle(s.runId, { status: "failed", error });
+            if (!settled)
+                await this.updateIndex((runs) => runs.filter((r) => r.runId !== s.runId));
+            else if (settled.wrote)
+                stamped.push(s.runId);
+        }
+        return stamped;
+    }
+    /**
+     * Parse `runs/<runId>.json` without any version check. Missing, unparseable and invalid-id (runPath
+     * throws) all collapse to `undefined` — the caller decides what "no record" means.
+     */
+    async readRecord(runId) {
+        try {
+            return JSON.parse(await readFile(this.runPath(runId), "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Read `index.json`; a missing or corrupt index reads as empty rather than failing, so a damaged
+     * index costs history, never the ability to start a run (the next write rewrites it).
+     */
+    async readIndex() {
+        try {
+            const parsed = JSON.parse(await readFile(join(this.opts.dir, INDEX_FILE), "utf8"));
+            return Array.isArray(parsed.runs) ? { version: 1, runs: parsed.runs } : { version: 1, runs: [] };
+        }
+        catch {
+            return { version: 1, runs: [] };
+        }
+    }
+    /**
+     * Serialized read-modify-write of the index; prunes past `keep` (never a running run) and deletes
+     * dropped files. A dropped row whose id is not a run id (a hand-edited index) loses its row but
+     * no file: `runPath` would throw on it, and one bad row must not break every later write — nor
+     * may it name a path outside `runs/`.
+     */
+    async updateIndex(fn) {
+        await this.mutex.withKeyLock(INDEX_LOCK, async () => {
+            const kept = [];
+            const dropped = [];
+            for (const r of fn((await this.readIndex()).runs)) {
+                (kept.length < this.keep || r.status === "running" ? kept : dropped).push(r);
+            }
+            await mkdir(this.opts.dir, { recursive: true });
+            await writeJsonAtomic(join(this.opts.dir, INDEX_FILE), { version: 1, runs: kept });
+            await Promise.all(dropped.filter((r) => QUANT_RUN_ID_RE.test(r.runId)).map((r) => rm(this.runPath(r.runId), { force: true })));
+        });
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/quant/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/quant/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,YAAY,GAOb,MAAM,YAAY,CAAC;AAEpB,6FAA6F;AAC7F,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAClC,yFAAyF;AACzF,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,GAAG,MAAM,CAAC;AAE1C,MAAM,UAAU,GAAG,YAAY,CAAC;AAChC,MAAM,QAAQ,GAAG,MAAM,CAAC;AACxB,MAAM,UAAU,GAAG,OAAO,CAAC;AAC3B,qGAAqG;AACrG,MAAM,eAAe,GAAG,MAAM,CAAC;AAqB/B,8FAA8F;AAC9F,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,IAAa;IACxD,MAAM,GAAG,GAAG,GAAG,IAAI,QAAQ,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IAC3E,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnE,MAAM,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,MAAsB;IACvC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IACtB,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC;QACvB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,MAAM,OAAO,gBAAgB;IAKE;IAJZ,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;IACzB,IAAI,CAAS;IACb,OAAO,CAAS;IAEjC,YAA6B,IAA6B;QAA7B,SAAI,GAAJ,IAAI,CAAyB;QACxD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,eAAe,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,cAAc,CAAC;IAChD,CAAC;IAED,sCAAsC;IACtC,QAAQ;QACN,OAAO,MAAM,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IAChD,CAAC;IAED,uGAAuG;IACvG,OAAO,CAAC,KAAa;QACnB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClG,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IACxD,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAqB,EAAE,aAAqB;QACtE,MAAM,MAAM,GAAmB;YAC7B,KAAK;YACL,UAAU,EAAE,iBAAiB;YAC7B,IAAI,EAAE;gBACJ,GAAG,OAAO;gBACV,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;gBACxD,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;gBAClD,aAAa;gBACb,MAAM,EAAE,SAAS;aAClB;SACF,CAAC;QACF,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,MAAM,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC;QAChG,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAwB;QAClD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,KAAK,0BAA0B,CAAC,CAAC;QAC5E,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAwB;QAC1D,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,eAAe,GAAG,KAAK,EAAE,EAAE,KAAK,IAAI,EAAE;YACrE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAC7C,IAAI,CAAC,OAAO,EAAE,IAAI;gBAAE,OAAO,SAAS,CAAC;YACrC,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACtC,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAChG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAC3C,CAAC;YACD,MAAM,IAAI,GAAmB;gBAC3B,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE;gBACtG,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;aAC3F,CAAC;YACF,MAAM,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;YACjD,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7F,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,KAAa;QACrB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACnD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,IAAI,MAAM,CAAC,UAAU,KAAK,iBAAiB,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;YAClF,MAAM,IAAI,mBAAmB,CAC3B,UAAU,CACR,qBAAqB,EACrB,OAAO,KAAK,6BAA6B,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,mCAAmC,iBAAiB,QAAQ,EAC9H,gDAAgD,KAAK,UAAU,CAChE,CACF,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI;QACR,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC;IAED,+FAA+F;IAC/F,KAAK,CAAC,SAAS,CAAC,OAAoE;QAClF,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QAC5F,IAAI,CAAC,GAAG,EAAE,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QACvG,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACzC,OAAO,MAAM,EAAE,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QAChF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,eAAe;QACnB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;gBAAE,SAAS;YACrC,MAAM,KAAK,GAAG,UAAU,CACtB,sBAAsB,EACtB,OAAO,CAAC,CAAC,KAAK,2DAA2D,EACzE,gDAAgD,YAAY,CAAC,CAAC,CAAC,EAAE,CAClE,CAAC;YACF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;YACxE,IAAI,CAAC,OAAO;gBAAE,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;iBACnF,IAAI,OAAO,CAAC,KAAK;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,UAAU,CAAC,KAAa;QACpC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAmB,CAAC;QACnF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,SAAS;QACrB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAAuB,CAAC;YACzG,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACnG,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAClC,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,WAAW,CAAC,EAAkD;QAC1E,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,IAAI,EAAE;YAClD,MAAM,IAAI,GAAsB,EAAE,CAAC;YACnC,MAAM,OAAO,GAAsB,EAAE,CAAC;YACtC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClD,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC/E,CAAC;YACD,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACnF,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAC5G,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/quant/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The quant desk's vocabulary inside the runtime: the engine's document (docVersion 1), the card
+ * schema the widget reads, the stored run record, and the refusal codes every surface prints.
+ *
+ * A leaf module with no imports, so the widgets module can depend on it without pulling in the job
+ * controller or the spawn helper. `QUANT_SECTIONS`, `QUANT_DOC_VERSION` and `QuantCardKind` are
+ * pinned against the Python engine by python-tests/quant/test_runtime_contract.py.
+ */
+/** The only document version this runtime reads. Any other version is refused, never guessed at. */
+export declare const QUANT_DOC_VERSION: 1;
+/** The engine's render sections, in render order (`render.SECTIONS`). */
+export declare const QUANT_SECTIONS: readonly ["overview", "strategy", "context", "protection", "performance", "leaks", "smart", "market", "edge", "scout", "next", "followups"];
+/** One renderable desk section. */
+export type QuantSection = (typeof QUANT_SECTIONS)[number];
+/** `qd-` + 8 hex. Every id is validated against this before it is joined into a path. */
+export declare const QUANT_RUN_ID_RE: RegExp;
+/** A Hyperliquid address as the engine accepts it. */
+export declare const QUANT_ADDRESS_RE: RegExp;
+/** The desk's window when none is asked for. */
+export declare const QUANT_DEFAULT_DAYS = 90;
+/** The widest window the runtime asks the engine for. */
+export declare const QUANT_MAX_DAYS = 365;
+/**
+ * A book can union at most this many wallets in one request. 25, not "every strategy wallet": the
+ * skill reads a senpi user's whole book, and users with more wallets than this pass the 25 with the
+ * most recent activity (the refusal in `parseStartParams` teaches exactly that). The engine's own
+ * breadth gate (coins touched, tape cap) still refuses a book too wide to read, whatever its count.
+ */
+export declare const QUANT_MAX_ADDRESSES = 25;
+/** Lifecycle of a run: `refused` = the engine answered "no" deterministically; `failed` = it could not answer. */
+export type QuantRunStatus = "running" | "done" | "failed" | "refused";
+/** Whose book: the reader's own (second person) or someone else's (analyst voice). */
+export type QuantWhose = "mine" | "other";
+/** The card kinds the engine emits. */
+export type QuantCardKind = "protect" | "leak" | "hire" | "build";
+/** The executable actions a card can carry. One today: place a stop loss on a position the reader holds. */
+export type QuantCardActionType = "set_stop_loss";
+/**
+ * One stop loss the protect card's Set stop loss button can place, as the engine priced it during the run
+ * (`deep.card_stop_losses`: the stop ladder's hard stop). Snake_case because it is the engine's field
+ * spelling and the client's wire contract; the client re-reads the live position before signing,
+ * so `mark` is a run-time snapshot, never a price to sign.
+ *
+ * Invariants the widget enforces before a client sees one (`parseQuantStopLoss`): every number finite
+ * and > 0, `trigger_px` on the losing side of `mark` (below it for a long, above for a short) and
+ * short of `liq_px` when there is one, `dex` equal to the coin's prefix ("" on the main dex,
+ * "xyz" for `xyz:TSLA` — the coin keeps its prefix), `wallet` a lowercased 0x address: the
+ * position's owner, which a single-wallet run fills with the document's address.
+ */
+export interface QuantStopLoss {
+    readonly coin: string;
+    readonly dex: string;
+    readonly side: "long" | "short";
+    /** Absolute position size. Informational: the order closes the whole position. */
+    readonly size: number;
+    readonly entry: number;
+    readonly mark: number;
+    readonly liq_px: number | null;
+    /** The ladder's hard stop. */
+    readonly trigger_px: number;
+    /** Distance from `mark`, in percent. */
+    readonly trigger_pct: number;
+    readonly wallet: `0x${string}`;
+}
+/** What a card lets the reader do. `stop_losses` is never empty — a card with none carries no action. */
+export interface QuantCardAction {
+    readonly type: QuantCardActionType;
+    readonly stop_losses: readonly QuantStopLoss[];
+}
+/**
+ * The allowlist of executable cards: the ONE action type each kind may carry, or null for none.
+ *
+ * The runtime is the single enforcement point (spec D3). The widget handler is the only code that
+ * turns a stored document into a client payload, and a stored document crossed a file boundary —
+ * an older or newer engine, a cached run, a hand-edited file — so the engine's own restraint is not
+ * trusted: `cardAction` strips any action this map does not allow before the payload is built.
+ * The engine is pinned to it by python-tests/quant/test_runtime_contract.py.
+ */
+export declare const ACTIONABLE_KINDS: Readonly<Record<QuantCardKind, QuantCardActionType | null>>;
+/**
+ * One recommendation card, exactly as the engine rendered it. Flat except for `action`. `usd`/`window`
+ * are the leak record's own values (null on non-leak cards); `cta` is text with no button semantics.
+ * `id` is stable per kind and position (today the engine emits `protect-1`, `leak-1`, `hire`,
+ * `build`; `leak-2` is legal), so it is typed as a string rather than an enum. Analyst (`other`)
+ * runs carry no cards. `action` is present only where {@link ACTIONABLE_KINDS} allows it (widget v2).
+ */
+export interface QuantCard {
+    readonly id: string;
+    readonly kind: QuantCardKind;
+    readonly title: string;
+    readonly detail: string;
+    readonly usd: number | null;
+    readonly window: string | null;
+    readonly cta: string;
+    readonly action?: QuantCardAction;
+}
+/**
+ * The engine's --json document plus `cards` and `doc_version`. Everything else is opaque here.
+ *
+ * The stored document crossed a strict-JSON boundary: the engine writes non-finite floats (e.g. a
+ * profit factor on an all-winning bucket) as the STRINGS `"Infinity"`, `"-Infinity"`, `"NaN"`, and
+ * `render --doc` restores them. So no opaque field may be assumed numeric — read them as `unknown`
+ * and narrow. `cards` are the exception: the engine only emits finite `usd` values there.
+ */
+export interface QuantDocument {
+    readonly doc_version: number;
+    readonly cards: readonly QuantCard[];
+    readonly address: string;
+    readonly days: number;
+    readonly whose?: string;
+    readonly [key: string]: unknown;
+}
+/** What a caller asks the desk for, after validation. Addresses are lowercased and de-duplicated. */
+export interface QuantRequest {
+    readonly addresses: readonly string[];
+    readonly days: number;
+    readonly whose: QuantWhose;
+    readonly book: boolean;
+    readonly force: boolean;
+}
+/** Stable refusal/failure codes. Refusals lead their message with `[CODE]`. */
+export type QuantErrorCode = "E_QUANT_INVALID_REQUEST" | "E_QUANT_UNSUPPORTED" | "E_QUANT_IN_PROGRESS" | "E_QUANT_NOT_FOUND" | "E_QUANT_DOC_VERSION" | "E_QUANT_NO_ACTIVITY" | "E_QUANT_NOT_A_TRADER" | "E_QUANT_UPSTREAM" | "E_QUANT_TIMEOUT" | "E_QUANT_ENGINE_ERROR";
+/** A refusal or failure: the bracketed message, the non-destructive next step, optional engine detail. */
+export interface QuantError {
+    readonly code: QuantErrorCode;
+    readonly message: string;
+    readonly what_to_do: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Build a {@link QuantError}. The message always leads with `[CODE]` — the CLI's exit-code
+ * classifier (`deploy/taxonomy.ts` `isRefusalMessage`) reads exactly that prefix.
+ */
+export declare function quantError(code: QuantErrorCode, text: string, whatToDo: string, details?: Record<string, unknown>): QuantError;
+/** The stored run's meta: the request plus timing, engine version and status. */
+export interface QuantRunMeta extends QuantRequest {
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+    readonly engineVersion: string;
+    readonly status: QuantRunStatus;
+}
+/** `runs/<runId>.json`. `document` only when done; `error` only when failed/refused. */
+export interface QuantRunRecord {
+    readonly runId: string;
+    readonly docVersion: number;
+    readonly meta: QuantRunMeta;
+    readonly document?: QuantDocument;
+    readonly error?: QuantError;
+}
+/** One row of `index.json` (newest first). `key` is {@link quantRequestKey}. */
+export interface QuantRunSummary {
+    readonly runId: string;
+    readonly key: string;
+    readonly addresses: readonly string[];
+    readonly days: number;
+    readonly whose: QuantWhose;
+    readonly book: boolean;
+    readonly status: QuantRunStatus;
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+}
+/** The read side the widget needs — injected at registration so widgets never construct a registry. */
+export interface QuantRunReader {
+    get(runId: string): Promise<QuantRunRecord | undefined>;
+    list(): Promise<readonly QuantRunSummary[]>;
+}
+/** A stored run exists but cannot be read by this runtime (e.g. another docVersion). */
+export declare class QuantRunLookupError extends Error {
+    readonly error: QuantError;
+    constructor(error: QuantError);
+}
+/** The single-flight key: the wallet set, case- and order-insensitive. */
+export declare function addressSetKey(addresses: readonly string[]): string;
+/**
+ * The freshness key: wallet set + days + voice + book. Voice is part of it on purpose — serving an
+ * analyst run to a reader asking about their own book would hand them a stranger's voice.
+ */
+export declare function quantRequestKey(req: Pick<QuantRequest, "addresses" | "days" | "whose" | "book">): string;
+/**
+ * The arguments of the CLI command that re-runs EXACTLY this request, for teaching text.
+ *
+ * Every field that changes the desk must be spelled, or a "run it again" hint quietly asks for a
+ * different desk: without `--other` an exit-4 `… --force` would tell the agent to force-read a vault
+ * as the reader's OWN book, and without `--days` a 30-day timeout would retry as 90 days. Defaults
+ * (own voice, {@link QUANT_DEFAULT_DAYS}) are omitted so the common command stays short. Stable
+ * order: addresses, `--book`, `--other`, `--days N`. `force` is never emitted — only the exit-4
+ * refusal may add it, deliberately.
+ *
+ * @param req The request (or a stored run's meta/summary, which carry the same fields).
+ * @returns e.g. `0xabc… --book --other --days 30`.
+ */
+export declare function quantRunArgs(req: Pick<QuantRequest, "addresses" | "book" | "whose" | "days">): string;
+/**
+ * Senpi's trader index, for the not-indexed answer (moved from the skill's references/coverage.json).
+ * Distinct wallets with closed positions in Senpi's index — never Hyperliquid's leaderboard row
+ * count (~46,600 rows; quoting that once overstated our coverage by 73%). The engine's exit-3
+ * refusal carries only `indexed` (true/false/unknown), never a count, so the runtime owns this
+ * figure and the skill hardcodes nothing. `staleAfterDays` bounds how long the exact count may be
+ * quoted after `asOf`; past it, `quoteAs` is the fallback phrasing and must never round upward.
+ */
+export declare const SENPI_INDEX_COVERAGE: {
+    readonly indexedWallets: 26188;
+    readonly asOf: "2026-09-21";
+    readonly staleAfterDays: 7;
+    readonly quoteAs: "over 25,000";
+};
+/**
+ * The index count to print: exact while fresh, the never-rounded-up fallback once stale (the
+ * skill's old rule). An index keeps growing after `asOf`, so an old exact figure is still a floor —
+ * but a stale "26,188" reads as current precision we no longer have, hence the round phrasing.
+ *
+ * @param nowMs Epoch milliseconds to judge staleness against (injected so callers and tests control time).
+ * @returns `indexedWallets` formatted en-US (e.g. "26,188") within `staleAfterDays` of `asOf`, else `quoteAs`.
+ */
+export declare function indexCoverageFigure(nowMs: number): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/quant/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/quant/types.ts"],"names":[],"mappings":"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"}

package/dist/quant/types.js

@@ -0,0 +1,121 @@
+/**
+ * The quant desk's vocabulary inside the runtime: the engine's document (docVersion 1), the card
+ * schema the widget reads, the stored run record, and the refusal codes every surface prints.
+ *
+ * A leaf module with no imports, so the widgets module can depend on it without pulling in the job
+ * controller or the spawn helper. `QUANT_SECTIONS`, `QUANT_DOC_VERSION` and `QuantCardKind` are
+ * pinned against the Python engine by python-tests/quant/test_runtime_contract.py.
+ */
+/** The only document version this runtime reads. Any other version is refused, never guessed at. */
+export const QUANT_DOC_VERSION = 1;
+/** The engine's render sections, in render order (`render.SECTIONS`). */
+export const QUANT_SECTIONS = [
+    "overview", "strategy", "context", "protection", "performance", "leaks",
+    "smart", "market", "edge", "scout", "next", "followups",
+];
+/** `qd-` + 8 hex. Every id is validated against this before it is joined into a path. */
+export const QUANT_RUN_ID_RE = /^qd-[0-9a-f]{8}$/;
+/** A Hyperliquid address as the engine accepts it. */
+export const QUANT_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+/** The desk's window when none is asked for. */
+export const QUANT_DEFAULT_DAYS = 90;
+/** The widest window the runtime asks the engine for. */
+export const QUANT_MAX_DAYS = 365;
+/**
+ * A book can union at most this many wallets in one request. 25, not "every strategy wallet": the
+ * skill reads a senpi user's whole book, and users with more wallets than this pass the 25 with the
+ * most recent activity (the refusal in `parseStartParams` teaches exactly that). The engine's own
+ * breadth gate (coins touched, tape cap) still refuses a book too wide to read, whatever its count.
+ */
+export const QUANT_MAX_ADDRESSES = 25;
+/**
+ * The allowlist of executable cards: the ONE action type each kind may carry, or null for none.
+ *
+ * The runtime is the single enforcement point (spec D3). The widget handler is the only code that
+ * turns a stored document into a client payload, and a stored document crossed a file boundary —
+ * an older or newer engine, a cached run, a hand-edited file — so the engine's own restraint is not
+ * trusted: `cardAction` strips any action this map does not allow before the payload is built.
+ * The engine is pinned to it by python-tests/quant/test_runtime_contract.py.
+ */
+export const ACTIONABLE_KINDS = {
+    protect: "set_stop_loss", leak: null, hire: null, build: null,
+};
+/**
+ * Build a {@link QuantError}. The message always leads with `[CODE]` — the CLI's exit-code
+ * classifier (`deploy/taxonomy.ts` `isRefusalMessage`) reads exactly that prefix.
+ */
+export function quantError(code, text, whatToDo, details) {
+    return {
+        code,
+        message: `[${code}] ${text}`,
+        what_to_do: whatToDo,
+        ...(details && Object.keys(details).length > 0 ? { details } : {}),
+    };
+}
+/** A stored run exists but cannot be read by this runtime (e.g. another docVersion). */
+export class QuantRunLookupError extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+        this.name = "QuantRunLookupError";
+    }
+}
+/** The single-flight key: the wallet set, case- and order-insensitive. */
+export function addressSetKey(addresses) {
+    return [...new Set(addresses.map((a) => a.trim().toLowerCase()))].sort().join(",");
+}
+/**
+ * The freshness key: wallet set + days + voice + book. Voice is part of it on purpose — serving an
+ * analyst run to a reader asking about their own book would hand them a stranger's voice.
+ */
+export function quantRequestKey(req) {
+    return `${req.book ? "book" : "one"}|${addressSetKey(req.addresses)}|${req.days}d|${req.whose}`;
+}
+/**
+ * The arguments of the CLI command that re-runs EXACTLY this request, for teaching text.
+ *
+ * Every field that changes the desk must be spelled, or a "run it again" hint quietly asks for a
+ * different desk: without `--other` an exit-4 `… --force` would tell the agent to force-read a vault
+ * as the reader's OWN book, and without `--days` a 30-day timeout would retry as 90 days. Defaults
+ * (own voice, {@link QUANT_DEFAULT_DAYS}) are omitted so the common command stays short. Stable
+ * order: addresses, `--book`, `--other`, `--days N`. `force` is never emitted — only the exit-4
+ * refusal may add it, deliberately.
+ *
+ * @param req The request (or a stored run's meta/summary, which carry the same fields).
+ * @returns e.g. `0xabc… --book --other --days 30`.
+ */
+export function quantRunArgs(req) {
+    const parts = [...req.addresses];
+    if (req.book)
+        parts.push("--book");
+    if (req.whose === "other")
+        parts.push("--other");
+    if (typeof req.days === "number" && req.days !== QUANT_DEFAULT_DAYS)
+        parts.push("--days", String(req.days));
+    return parts.join(" ");
+}
+/**
+ * Senpi's trader index, for the not-indexed answer (moved from the skill's references/coverage.json).
+ * Distinct wallets with closed positions in Senpi's index — never Hyperliquid's leaderboard row
+ * count (~46,600 rows; quoting that once overstated our coverage by 73%). The engine's exit-3
+ * refusal carries only `indexed` (true/false/unknown), never a count, so the runtime owns this
+ * figure and the skill hardcodes nothing. `staleAfterDays` bounds how long the exact count may be
+ * quoted after `asOf`; past it, `quoteAs` is the fallback phrasing and must never round upward.
+ */
+export const SENPI_INDEX_COVERAGE = { indexedWallets: 26_188, asOf: "2026-09-21", staleAfterDays: 7, quoteAs: "over 25,000" };
+/**
+ * The index count to print: exact while fresh, the never-rounded-up fallback once stale (the
+ * skill's old rule). An index keeps growing after `asOf`, so an old exact figure is still a floor —
+ * but a stale "26,188" reads as current precision we no longer have, hence the round phrasing.
+ *
+ * @param nowMs Epoch milliseconds to judge staleness against (injected so callers and tests control time).
+ * @returns `indexedWallets` formatted en-US (e.g. "26,188") within `staleAfterDays` of `asOf`, else `quoteAs`.
+ */
+export function indexCoverageFigure(nowMs) {
+    const ageDays = (nowMs - Date.parse(`${SENPI_INDEX_COVERAGE.asOf}T00:00:00Z`)) / 86_400_000;
+    return ageDays <= SENPI_INDEX_COVERAGE.staleAfterDays
+        ? SENPI_INDEX_COVERAGE.indexedWallets.toLocaleString("en-US")
+        : SENPI_INDEX_COVERAGE.quoteAs;
+}
+//# sourceMappingURL=types.js.map

package/dist/quant/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/quant/types.ts"],"names":[],"mappings":"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"}

package/dist/skills-manager/manifest.js

@@ -67,7 +67,7 @@ export const FALLBACK_MANIFEST = {
         { name: "senpi-improve-trades", maxMajor: 1 },
         { name: "senpi-market-pulse", maxMajor: 1 },
         { name: "senpi-smart-money", maxMajor: 1 },
-        { name: "quant-desk", maxMajor: 1 },
+        { name: "quant-desk", maxMajor: 2 },
         { name: "senpi-signals", maxMajor: 2 },
         { name: "senpi-trader-research", maxMajor: 1 },
         { name: "senpi-trade", maxMajor: 1 },