@senpi/runtime 3.0.148 → 3.0.150

package/dist/quant/job.js

@@ -0,0 +1,184 @@
+import { addressSetKey, quantError, quantRunArgs } from "./types.js";
+/**
+ * A start refused because the same wallet set already has a run in flight. Carries the running id
+ * so the refusal can name it and `senpi quant status <id>` — a second run would not finish the first
+ * any sooner, it would only halve both runs' share of Hyperliquid's rate limit.
+ */
+export class QuantInProgressError extends Error {
+    runId;
+    addresses;
+    constructor(runId, addresses) {
+        super(`quant run ${runId} is already running on ${addresses.join(", ")}`);
+        this.runId = runId;
+        this.addresses = addresses;
+        this.name = "QuantInProgressError";
+    }
+}
+/**
+ * A start refused because the boot janitor (stamping runs a restart cut short) failed. Kept apart
+ * from other start failures so the gateway can name the recovery step: the quant state dir must be
+ * writable; the next start retries the cleanup.
+ */
+export class QuantJanitorError extends Error {
+    cause;
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.cause = cause;
+        this.name = "QuantJanitorError";
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Map the runner's outcome onto the registry's finish shape. */
+function toRunOutcome(o) {
+    return o.ok ? { status: "done", document: o.document } : { status: o.status, error: o.error };
+}
+/** Single-flight desk runs. See the module doc for the slot and restart invariants. */
+export class QuantJobController {
+    opts;
+    bySet = new Map();
+    byId = new Map();
+    janitor;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Run the registry's boot janitor once per process and answer the ids it stamped failed.
+     *
+     * Memoized: the plugin service calls it at start (to log what a restart cut short), and `start`
+     * awaits it before claiming a slot, whichever comes first. A failure is NOT memoized — the next
+     * caller retries — and `start` refuses while it fails, so this process never creates a run the
+     * janitor has not yet had a chance to run ahead of (which it would then stamp as dead).
+     */
+    recoverInterrupted() {
+        if (!this.janitor) {
+            const attempt = this.opts.registry.markInterrupted();
+            this.janitor = attempt;
+            attempt.catch(() => {
+                if (this.janitor === attempt)
+                    this.janitor = undefined;
+            });
+        }
+        return this.janitor;
+    }
+    /**
+     * Serve a fresh run, or claim the wallet set's slot and start the engine detached.
+     *
+     * Order: janitor → freshness (async) → check-and-claim (sync) → create record → spawn. The claim
+     * follows the last await before it, so of two simultaneous starts exactly one claims and the other
+     * sees the slot taken.
+     *
+     * @throws {QuantInProgressError} when the wallet set (case- and order-insensitive) has a run in flight.
+     * @throws {QuantJanitorError} when the boot janitor fails; nothing runs, the next start retries it.
+     * @throws When the record write fails; the slot is released and nothing runs.
+     */
+    async start(request, options) {
+        await this.recoverInterrupted().catch((err) => {
+            throw new QuantJanitorError(err);
+        });
+        if (!options.fresh) {
+            const hit = await this.opts.registry.findFresh(request);
+            if (hit)
+                return { runId: hit.runId, status: "done", cached: true };
+        }
+        const key = addressSetKey(request.addresses);
+        const running = this.bySet.get(key);
+        if (running)
+            throw new QuantInProgressError(running.runId, running.request.addresses);
+        const live = { runId: this.opts.registry.newRunId(), key, request };
+        this.bySet.set(key, live); // claimed synchronously after the last await above
+        // Live BEFORE the record exists: `status` reads "running on disk, not live" as dead, so a read
+        // landing in the create window must already find the run live.
+        this.byId.set(live.runId, live);
+        try {
+            await this.opts.registry.create(live.runId, request, this.opts.engineVersion);
+        }
+        catch (err) {
+            this.bySet.delete(key);
+            this.byId.delete(live.runId);
+            throw err;
+        }
+        live.settled = this.execute(live);
+        return { runId: live.runId, status: "running", cached: false };
+    }
+    /**
+     * A run's status; no id = the newest run. `undefined` when there is no such run (including an
+     * invalid, path-like id — the registry never resolves one). Waits for the boot janitor, so a run a
+     * restart cut short reads `failed`, never `running`. A janitor failure does not block reads.
+     *
+     * A record that says `running` while this process has no live job for it is dead — every run of
+     * this process is live from before its record is written until after its outcome is — whether the
+     * outcome could not be recorded (disk full after create) or a failing janitor left a restart's
+     * row. It is answered `failed` with the re-run command, and stamped failed best-effort (the
+     * registry keeps the first outcome, so this can never overwrite a real one).
+     *
+     * @throws {QuantRunLookupError} (from the registry) for a record of another docVersion.
+     */
+    async status(runId) {
+        await this.recoverInterrupted().catch(() => undefined);
+        const id = runId ?? (await this.opts.registry.list())[0]?.runId;
+        if (!id)
+            return undefined;
+        const record = await this.opts.registry.get(id);
+        if (!record)
+            return undefined;
+        const live = this.byId.get(id);
+        if (!live && record.meta.status === "running") {
+            const error = quantError("E_QUANT_ENGINE_ERROR", `run ${id} is not running in this gateway: it stopped without recording an outcome.`, `Run the desk again: openclaw senpi quant run ${quantRunArgs(record.meta)}`);
+            const stored = await this.opts.registry.finish(id, { status: "failed", error }).catch((err) => {
+                this.opts.log(`quant run ${id}: could not stamp a dead run failed: ${errorText(err)}`);
+                return undefined;
+            });
+            const finishedAt = stored?.meta.finishedAt;
+            return {
+                runId: id,
+                status: stored && stored.meta.status !== "running" ? stored.meta.status : "failed",
+                startedAt: record.meta.startedAt,
+                ...(finishedAt ? { finishedAt } : {}),
+                error: stored?.error ?? error,
+                addresses: record.meta.addresses,
+                days: record.meta.days,
+            };
+        }
+        return {
+            runId: id,
+            status: live ? "running" : record.meta.status,
+            startedAt: record.meta.startedAt,
+            ...(record.meta.finishedAt ? { finishedAt: record.meta.finishedAt } : {}),
+            ...(live?.progress ? { progress: live.progress } : {}),
+            ...(record.error ? { error: record.error } : {}),
+            addresses: record.meta.addresses,
+            days: record.meta.days,
+        };
+    }
+    /** Resolves when a live run has been finished into the registry (immediately if not live). Tests use it. */
+    waitFor(runId) {
+        return this.byId.get(runId)?.settled ?? Promise.resolve();
+    }
+    /**
+     * Run the engine and record its outcome. Never rejects: an engine that throws (spawn exploded) is
+     * recorded as `E_QUANT_ENGINE_ERROR`, and a failure to record even that is logged. The slot is
+     * always released, so a wallet can never stay busy after its run ended. The registry's `finish`
+     * keeps the first outcome, so a late second finisher cannot overwrite a delivered desk.
+     */
+    async execute(live) {
+        try {
+            const outcome = await this.opts.runEngine(live.request, (line) => {
+                if (line.startsWith("[quant-desk]"))
+                    live.progress = line;
+            });
+            await this.opts.registry.finish(live.runId, toRunOutcome(outcome));
+        }
+        catch (err) {
+            this.opts.log(`quant run ${live.runId} failed outside the engine: ${errorText(err)}`);
+            const error = quantError("E_QUANT_ENGINE_ERROR", `the desk could not be run: ${errorText(err)}.`, "This is a fault in the runtime, not in the wallet. Quote the error; do not retry in a loop.");
+            await this.opts.registry.finish(live.runId, { status: "failed", error }).catch((e) => this.opts.log(`quant run ${live.runId}: could not record the failure: ${errorText(e)}`));
+        }
+        finally {
+            this.bySet.delete(live.key);
+            this.byId.delete(live.runId);
+        }
+    }
+}
+//# sourceMappingURL=job.js.map

package/dist/quant/job.js.map

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

package/dist/quant/register.d.ts

@@ -0,0 +1,53 @@
+import { type RenderOutcome } from "./engine-runner.js";
+import { QuantJobController } from "./job.js";
+import { QuantRunRegistry } from "./registry.js";
+import { type QuantError, type QuantRequest, type QuantSection } from "./types.js";
+/** The engine package's parent directory: dist/quant/engine when built, src/quant/engine under vitest. */
+export declare const QUANT_ENGINE_DIR: string;
+/** The slice of the plugin API this module uses. */
+export interface QuantPluginApi {
+    registerGatewayMethod(name: string, handler: (ctx: {
+        respond: (ok: boolean, value: unknown) => void;
+        params?: Record<string, unknown>;
+    }) => void | Promise<void>, opts?: {
+        scope?: "operator.write" | "operator.read";
+    }): void;
+}
+/** Everything the handlers need, injected (tests pass a stub renderer; production spawns render.py). */
+export interface QuantGatewayContext {
+    controller: QuantJobController;
+    registry: QuantRunRegistry;
+    renderMarkdown(runFile: string, sections: readonly QuantSection[]): Promise<RenderOutcome>;
+}
+/** Validate `senpi.quant.start` params into a {@link QuantRequest}. Exported for tests. */
+export declare function parseStartParams(params: Record<string, unknown> | undefined): {
+    ok: true;
+    request: QuantRequest;
+    fresh: boolean;
+} | {
+    ok: false;
+    error: QuantError;
+};
+/** Register the four quant transport methods with explicit scopes (never the admin fallback). */
+export declare function registerQuantGatewayMethods(api: QuantPluginApi, ctx: QuantGatewayContext): void;
+/** Options for {@link createQuantDesk}. `stateDir` is `<senpi-state>/quant`; `pythonBin`/`engineDir`/`now` are test seams. */
+export interface CreateQuantDeskOptions {
+    stateDir: string;
+    senpiAuthToken?: string;
+    logger: {
+        info(line: string): void;
+    };
+    pythonBin?: string;
+    engineDir?: string;
+    now?: () => number;
+}
+/**
+ * Build and register the quant desk. Does no I/O until a method is called or the boot janitor runs.
+ * The returned registry is for in-process readers (show_widget); the controller is for the service
+ * start hook, which calls `recoverInterrupted()` to log what a restart cut short.
+ */
+export declare function createQuantDesk(api: QuantPluginApi, opts: CreateQuantDeskOptions): {
+    registry: QuantRunRegistry;
+    controller: QuantJobController;
+};
+//# sourceMappingURL=register.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/quant/register.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAA2C,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAE0C,KAAK,UAAU,EAAE,KAAK,YAAY,EAAwB,KAAK,YAAY,EAC3H,MAAM,YAAY,CAAC;AAEpB,0GAA0G;AAC1G,eAAO,MAAM,gBAAgB,QAAsD,CAAC;AAEpF,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,qBAAqB,CACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC5H,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,eAAe,CAAA;KAAE,GACpD,IAAI,CAAC;CACT;AAED,wGAAwG;AACxG,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC5F;AA2BD,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAkCxF;AAwJD,iGAAiG;AACjG,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAK/F;AAED,8HAA8H;AAC9H,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE;QAAE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,sBAAsB,GAAG;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,kBAAkB,CAAA;CAAE,CAejJ"}

package/dist/quant/register.js

@@ -0,0 +1,253 @@
+/**
+ * Gateway wiring for the quant desk: `senpi.quant.{start,status,get,list}`.
+ *
+ * Like the deploy pair, these are transport between the `senpi quant` CLI and the plugin; the CLI
+ * is the teaching surface. `createQuantDesk` builds the registry, controller and runner from an
+ * explicit context and returns the registry so index.ts can hand it to show_widget and to the boot
+ * janitor — nothing here reaches into the plugin's boot closure.
+ *
+ * Refusals lead with `[E_QUANT_*]` (the CLI exits 2 on them); internal failures carry no bracket
+ * (the CLI exits 1). Every refusal ends in a non-destructive next step (`Next: …`).
+ *
+ * The read methods wait for the controller's boot janitor (`recoverInterrupted`) like `start` does,
+ * so neither `status` nor `get` nor `list` can show a run a restart cut short as `running`.
+ */
+import { fileURLToPath } from "node:url";
+import { VERSION } from "../version.js";
+import { renderQuantMarkdown, runQuantEngine } from "./engine-runner.js";
+import { QuantInProgressError, QuantJanitorError, QuantJobController } from "./job.js";
+import { QuantRunRegistry } from "./registry.js";
+import { QUANT_ADDRESS_RE, QUANT_DEFAULT_DAYS, QUANT_RUN_ID_RE, QUANT_MAX_ADDRESSES, QUANT_MAX_DAYS, QUANT_SECTIONS, QuantRunLookupError, quantError, quantRunArgs, } from "./types.js";
+/** The engine package's parent directory: dist/quant/engine when built, src/quant/engine under vitest. */
+export const QUANT_ENGINE_DIR = fileURLToPath(new URL("./engine", import.meta.url));
+/** The generic start command, for refusals that have no request to spell back. */
+const RUN_USAGE = "openclaw senpi quant run <0x address>";
+/** A malformed request: nothing was started, fix it and run again. */
+function invalid(text) {
+    return quantError("E_QUANT_INVALID_REQUEST", `${text} Nothing was started.`, `Fix the request and run it again: ${RUN_USAGE}`);
+}
+/** Refusal on the wire: the bracketed message plus its next step, so the CLI's stderr carries both. */
+function refuse(respond, error) {
+    respond(false, undefined, { code: error.code, message: `${error.message} Next: ${error.what_to_do}` });
+}
+/** Internal failure on the wire: no bracket anywhere, so the CLI classifies it as exit 1. */
+function unavailable(respond, text) {
+    respond(false, undefined, { code: "UNAVAILABLE", message: text.replace(/\[[A-Z][A-Z0-9_]*\]\s*/g, "") });
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Validate `senpi.quant.start` params into a {@link QuantRequest}. Exported for tests. */
+export function parseStartParams(params) {
+    const p = params ?? {};
+    if (!Array.isArray(p.addresses) || p.addresses.length === 0) {
+        return { ok: false, error: invalid(`"addresses" must list 1 to ${QUANT_MAX_ADDRESSES} Hyperliquid addresses.`) };
+    }
+    // Too wide a book gets its own refusal: "fix the request" does not say WHICH wallets to keep,
+    // and an agent reading a user's strategy wallets needs to be told how to choose.
+    if (p.addresses.length > QUANT_MAX_ADDRESSES) {
+        return { ok: false, error: quantError("E_QUANT_INVALID_REQUEST", `a book reads at most ${QUANT_MAX_ADDRESSES} wallets; got ${p.addresses.length}. Nothing was started.`, `pass the ${QUANT_MAX_ADDRESSES} with the most recent activity (strategy_list shows lastActivity) — openclaw senpi quant run <up to ${QUANT_MAX_ADDRESSES}> --book`) };
+    }
+    const addresses = [];
+    for (const a of p.addresses) {
+        if (typeof a !== "string" || !QUANT_ADDRESS_RE.test(a.trim())) {
+            return { ok: false, error: invalid(`not a Hyperliquid address: ${JSON.stringify(a)} — expected 0x followed by 40 hex characters.`) };
+        }
+        const lower = a.trim().toLowerCase();
+        if (!addresses.includes(lower))
+            addresses.push(lower);
+    }
+    const book = p.book === true;
+    const days = p.days === undefined ? QUANT_DEFAULT_DAYS : p.days;
+    if (typeof days !== "number" || !Number.isInteger(days) || days < 1 || days > QUANT_MAX_DAYS) {
+        return { ok: false, error: invalid(`"days" must be a whole number from 1 to ${QUANT_MAX_DAYS}.`) };
+    }
+    const whose = p.whose === undefined ? "mine" : p.whose;
+    if (whose !== "mine" && whose !== "other")
+        return { ok: false, error: invalid(`"whose" must be "mine" or "other".`) };
+    // Checked after days/whose so the book hint re-asks for the SAME window and voice (quantRunArgs).
+    if (addresses.length > 1 && !book) {
+        return { ok: false, error: quantError("E_QUANT_UNSUPPORTED", "several addresses without --book is a side-by-side comparison, which the runtime does not run yet. Nothing was started.", `To read them as ONE book (a senpi user's strategy wallets): openclaw senpi quant run ${quantRunArgs({ addresses, book: true, whose, days })}`) };
+    }
+    return { ok: true, fresh: p.fresh === true, request: { addresses, days, whose, book, force: p.force === true } };
+}
+/** Validate `sections` against the engine's render sections; an unknown one is refused naming them all. */
+function parseSections(raw) {
+    if (raw === undefined)
+        return [];
+    const known = QUANT_SECTIONS;
+    if (!Array.isArray(raw) || raw.some((s) => typeof s !== "string" || !known.includes(s))) {
+        return quantError("E_QUANT_INVALID_REQUEST", `unknown section in ${JSON.stringify(raw)}.`, `Sections: ${QUANT_SECTIONS.join(", ")}.`);
+    }
+    return raw;
+}
+/**
+ * The NOT_FOUND refusal. Names up to five recent run ids and the list command, so an agent holding a
+ * stale or mistyped id (or a path-like one, which the registry never resolves) has a way forward.
+ */
+async function notFound(registry, runId) {
+    if (runId === undefined) {
+        return quantError("E_QUANT_NOT_FOUND", "no quant run has been started on this agent.", `Start one: ${RUN_USAGE}`);
+    }
+    const recent = (await registry.list()).slice(0, 5).map((r) => r.runId);
+    return quantError("E_QUANT_NOT_FOUND", `no quant run ${JSON.stringify(runId)} on this agent. ${recent.length > 0 ? `Recent runs: ${recent.join(", ")}.` : "No runs yet."}`, "List them: openclaw senpi quant list");
+}
+/**
+ * The refusal for a run the index knows but whose stored record cannot be used: the file is corrupt
+ * or gone, it is `done` with no document, or render.py could not read it. NOT_FOUND-style, because
+ * there is no desk to show — but unlike a plain NOT_FOUND it names the exact re-run command, so an
+ * agent does not loop between `list` (which shows the run) and `get` (which cannot read it).
+ * `--fresh` so the re-run cannot be served from anything cached for the same request.
+ */
+function unreadableRun(runId, why, request) {
+    return quantError("E_QUANT_NOT_FOUND", `stored run ${runId} is unreadable (${why}); there is no desk to show for it.`, `Re-run the desk: openclaw senpi quant run ${quantRunArgs(request)} --fresh`, { runId });
+}
+/**
+ * The index row for a run id whose record did not read, if any — the corrupt-at-rest case. `list`
+ * shows such a run, so answering a plain "no such run" would contradict it. Undefined for ids that
+ * are not run ids (path-like) and for ids the index does not know.
+ */
+async function indexedRow(registry, runId) {
+    const rows = await registry.list();
+    const id = runId ?? rows[0]?.runId;
+    if (id === undefined || !QUANT_RUN_ID_RE.test(id))
+        return undefined;
+    return rows.find((r) => r.runId === id);
+}
+/** Wait for the boot janitor on a read path; a janitor failure never blocks a read. */
+async function afterJanitor(ctx) {
+    await ctx.controller.recoverInterrupted().catch(() => undefined);
+}
+/** `senpi.quant.start`: validate, start or serve fresh, answer `{runId, status, cached, monitor}`. */
+async function handleStart(ctx, params, respond) {
+    const parsed = parseStartParams(params);
+    if (!parsed.ok)
+        return refuse(respond, parsed.error);
+    try {
+        const started = await ctx.controller.start(parsed.request, { fresh: parsed.fresh });
+        respond(true, { ...started, monitor: `openclaw senpi quant status ${started.runId}` });
+    }
+    catch (err) {
+        if (err instanceof QuantInProgressError) {
+            return refuse(respond, quantError("E_QUANT_IN_PROGRESS", `a desk on ${err.addresses.join(", ")} is already running as run ${err.runId}. A second run does not make the first finish — both would share Hyperliquid's rate limit.`, `Watch the one in flight: openclaw senpi quant status ${err.runId}`, { runId: err.runId }));
+        }
+        if (err instanceof QuantJanitorError) {
+            return unavailable(respond, `the quant state dir could not be cleaned up after a restart: ${errorText(err.cause)}. Nothing was started; make the quant state dir writable, and the next start retries the cleanup.`);
+        }
+        unavailable(respond, `could not start the desk: ${errorText(err)}. Nothing is running for this request; check the gateway log.`);
+    }
+}
+/** `senpi.quant.status`: one run's status, or the newest run's when no id is given. */
+async function handleStatus(ctx, params, respond) {
+    const runId = params?.runId;
+    if (runId !== undefined && typeof runId !== "string")
+        return refuse(respond, invalid(`"runId" must be a string.`));
+    try {
+        const status = await ctx.controller.status(runId);
+        if (!status) {
+            const row = await indexedRow(ctx.registry, runId);
+            if (row)
+                return refuse(respond, unreadableRun(row.runId, "its file is missing or not valid JSON", row));
+            return refuse(respond, await notFound(ctx.registry, runId));
+        }
+        respond(true, status);
+    }
+    catch (err) {
+        if (err instanceof QuantRunLookupError)
+            return refuse(respond, err.error);
+        unavailable(respond, `could not read the run: ${errorText(err)}`);
+    }
+}
+/**
+ * `senpi.quant.get`: a run's stored document (`json`) or its Markdown re-rendered by render.py
+ * (`markdown`, the default) — never recomputed. A run that is not done answers its status and no
+ * document. A stored run that cannot be used — its file corrupt or gone while the index lists it, a
+ * `done` record with no document, or render.py unable to read it — is a NOT_FOUND-style refusal
+ * with the exact re-run command ({@link unreadableRun}); any other render failure is internal (no
+ * bracket).
+ */
+async function handleGet(ctx, params, respond) {
+    const sections = parseSections(params?.sections);
+    if (!Array.isArray(sections))
+        return refuse(respond, sections);
+    const format = params?.format ?? "markdown";
+    if (format !== "markdown" && format !== "json")
+        return refuse(respond, invalid(`"format" must be "markdown" or "json".`));
+    const runId = params?.runId;
+    if (typeof runId !== "string")
+        return refuse(respond, invalid(`"runId" is required.`));
+    await afterJanitor(ctx);
+    let record;
+    try {
+        record = await ctx.registry.get(runId);
+    }
+    catch (err) {
+        if (err instanceof QuantRunLookupError)
+            return refuse(respond, err.error);
+        return unavailable(respond, `could not read the run: ${errorText(err)}`);
+    }
+    if (!record) {
+        const row = await indexedRow(ctx.registry, runId);
+        if (row)
+            return refuse(respond, unreadableRun(runId, "its file is missing or not valid JSON", row));
+        return refuse(respond, await notFound(ctx.registry, runId));
+    }
+    if (record.meta.status === "done" && !record.document) {
+        return refuse(respond, unreadableRun(runId, "the stored run has no document", record.meta));
+    }
+    if (record.meta.status !== "done" || !record.document) {
+        return respond(true, { runId, docVersion: record.docVersion, status: record.meta.status, ...(record.error ? { error: record.error } : {}) });
+    }
+    if (format === "json")
+        return respond(true, { runId, docVersion: record.docVersion, status: "done", document: record.document });
+    const rendered = await ctx.renderMarkdown(ctx.registry.runPath(runId), sections);
+    if (!rendered.ok && rendered.storedRunUnreadable !== undefined) {
+        return refuse(respond, unreadableRun(runId, rendered.storedRunUnreadable, record.meta));
+    }
+    if (!rendered.ok)
+        return unavailable(respond, `the stored desk could not be rendered: ${rendered.error.message}`);
+    respond(true, { runId, docVersion: record.docVersion, status: "done", markdown: rendered.markdown });
+}
+/**
+ * `senpi.quant.list`: the whole index, newest first. Rows carry `runId, addresses, days, whose,
+ * book, status, startedAt, finishedAt`. The index's freshness `key` is internal and stripped here,
+ * so the wire shape is exactly the documented one.
+ */
+async function handleList(ctx, respond) {
+    await afterJanitor(ctx);
+    try {
+        respond(true, { runs: (await ctx.registry.list()).map(({ key: _key, ...row }) => row) });
+    }
+    catch (err) {
+        unavailable(respond, `could not list quant runs: ${errorText(err)}`);
+    }
+}
+/** Register the four quant transport methods with explicit scopes (never the admin fallback). */
+export function registerQuantGatewayMethods(api, ctx) {
+    api.registerGatewayMethod("senpi.quant.start", async (g) => handleStart(ctx, g.params, g.respond), { scope: "operator.write" });
+    api.registerGatewayMethod("senpi.quant.status", async (g) => handleStatus(ctx, g.params, g.respond), { scope: "operator.read" });
+    api.registerGatewayMethod("senpi.quant.get", async (g) => handleGet(ctx, g.params, g.respond), { scope: "operator.read" });
+    api.registerGatewayMethod("senpi.quant.list", async (g) => handleList(ctx, g.respond), { scope: "operator.read" });
+}
+/**
+ * Build and register the quant desk. Does no I/O until a method is called or the boot janitor runs.
+ * The returned registry is for in-process readers (show_widget); the controller is for the service
+ * start hook, which calls `recoverInterrupted()` to log what a restart cut short.
+ */
+export function createQuantDesk(api, opts) {
+    const registry = new QuantRunRegistry({ dir: opts.stateDir, now: opts.now ?? (() => Date.now()) });
+    const spawnOpts = {
+        engineDir: opts.engineDir ?? QUANT_ENGINE_DIR,
+        ...(opts.pythonBin ? { pythonBin: opts.pythonBin } : {}),
+        ...(opts.senpiAuthToken ? { senpiAuthToken: opts.senpiAuthToken } : {}),
+    };
+    const controller = new QuantJobController({
+        registry,
+        engineVersion: VERSION,
+        log: (line) => opts.logger.info(`[senpi-quant] ${line}`),
+        runEngine: (request, onProgress) => runQuantEngine(request, { ...spawnOpts, stateDir: opts.stateDir, onStderrLine: onProgress }),
+    });
+    registerQuantGatewayMethods(api, { controller, registry, renderMarkdown: (file, sections) => renderQuantMarkdown(file, sections, spawnOpts) });
+    return { registry, controller };
+}
+//# sourceMappingURL=register.js.map

package/dist/quant/register.js.map

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

package/dist/quant/registry.d.ts

@@ -0,0 +1,105 @@
+import { type QuantDocument, type QuantError, type QuantRequest, type QuantRunReader, type QuantRunRecord, type QuantRunSummary } from "./types.js";
+/** Runs retained; older ones are deleted with their files. Running runs are never pruned. */
+export declare const QUANT_KEEP_RUNS = 20;
+/** A done run for the same request younger than this is served instead of recomputed. */
+export declare const QUANT_FRESH_MS: number;
+/** How a run ended, as the job controller reports it. */
+export type QuantRunOutcome = {
+    readonly status: "done";
+    readonly document: QuantDocument;
+} | {
+    readonly status: "failed" | "refused";
+    readonly error: QuantError;
+};
+/** Construction options; `now` is injected so freshness is testable without timers. */
+export interface QuantRunRegistryOptions {
+    dir: string;
+    now(): number;
+    keep?: number;
+    freshMs?: number;
+}
+/** File-backed registry of quant runs. See the module doc for the layout and invariants. */
+export declare class QuantRunRegistry implements QuantRunReader {
+    private readonly opts;
+    private readonly mutex;
+    private readonly keep;
+    private readonly freshMs;
+    constructor(opts: QuantRunRegistryOptions);
+    /** A fresh run id (`qd-` + 8 hex). */
+    newRunId(): string;
+    /** The record path for a VALID run id. Throws on anything else, so no caller can build a traversal. */
+    runPath(runId: string): string;
+    /** Record a new `running` run and put it at the head of the index. */
+    create(runId: string, request: QuantRequest, engineVersion: string): Promise<QuantRunRecord>;
+    /**
+     * 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).
+     */
+    finish(runId: string, outcome: QuantRunOutcome): Promise<QuantRunRecord>;
+    /**
+     * 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.
+     */
+    private settle;
+    /**
+     * 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.
+     */
+    get(runId: string): Promise<QuantRunRecord | undefined>;
+    /**
+     * 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.
+     */
+    list(): Promise<QuantRunSummary[]>;
+    /** The newest done run for this exact request finished within the freshness window, if any. */
+    findFresh(request: Pick<QuantRequest, "addresses" | "days" | "whose" | "book">): Promise<QuantRunRecord | 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.
+     */
+    markInterrupted(): Promise<string[]>;
+    /**
+     * 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.
+     */
+    private readRecord;
+    /**
+     * 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).
+     */
+    private readIndex;
+    /**
+     * 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/`.
+     */
+    private updateIndex;
+}
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/quant/registry.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAEpB,6FAA6F;AAC7F,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,yFAAyF;AACzF,eAAO,MAAM,cAAc,QAAc,CAAC;AAc1C,yDAAyD;AACzD,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAE1E,uFAAuF;AACvF,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,IAAI,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA4BD,4FAA4F;AAC5F,qBAAa,gBAAiB,YAAW,cAAc;IAKzC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEJ,IAAI,EAAE,uBAAuB;IAK1D,sCAAsC;IACtC,QAAQ,IAAI,MAAM;IAIlB,uGAAuG;IACvG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAK9B,sEAAsE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkBlG;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAM9E;;;;;;;OAOG;YACW,MAAM;IAoBpB;;;OAGG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAiB7D;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAIxC,+FAA+F;IACzF,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAY1H;;;;;;;;;;;;;;OAcG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAgB1C;;;OAGG;YACW,UAAU;IAQxB;;;OAGG;YACW,SAAS;IASvB;;;;;OAKG;YACW,WAAW;CAc1B"}