@johannc-dev/zyrk 0.2.1 → 0.2.2

package/README.md

@@ -53,6 +53,13 @@ npx zyrk run wallet countBuys '{"wallet":"…","sinceMs":0,"untilMs":3600000}'
 autres API réseau dans votre code, et l'ancienne API 0.1 (`ctx.data.query`,
 `ctx.data.pages`) avec un guide de migration.
 
+Supprimer un programme : `npx zyrk delete wallet` (demande confirmation ;
+`--yes` dans un script) ou `client.delete("wallet")`. Partent ses versions,
+son état, ses abonnements, ses exécutions (celles en cours sont annulées) et
+ses replays ; `ctx.storage` reste (il appartient au compte). La place est
+libérée tout de suite et le même nom redéployé repart de zéro. Un programme
+absent répond `404 program_not_found`.
+
 Modules :
 
 | Import                        | Contenu                                               |

package/dist/cli.d.ts

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
-export declare const VERSION = "0.2.1";
+export declare const VERSION = "0.2.2";
 /** `2026-11-07`, `2026-11-07T13:00:00Z` or milliseconds since the epoch. */
 export declare function timeOf(text: string): number;
+/**
+ * Whether `zyrk delete` may go on: `--yes`, or a `y` typed at the prompt.
+ * Without a terminal (a script, CI) and without `--yes` it refuses.
+ */
+export declare function confirmDeletion(name: string, yes: boolean, interactive?: boolean): Promise<boolean>;

package/dist/cli.js

@@ -5,10 +5,10 @@ import { ChildProcessSpawner } from "effect/process";
 import { BUNDLE_PATH, writeBundleEffect } from "./build.js";
 import { ZyrkClient } from "./client.js";
 import { decode, Json } from "./contracts.js";
-import { exportHistory, exportTotals, exportVolumeSearch, } from "./export.js";
+import { exportHistory, exportTotals, exportVolumeSearch, exportCompute, } from "./export.js";
 import { LocalRunner } from "./local.js";
 import { DecodeError, messageOf, } from "./errors.js";
-export const VERSION = "0.2.1";
+export const VERSION = "0.2.2";
 const print = (value) => Console.log(JSON.stringify(value, null, 2));
 const entry = Argument.String("entry.ts").pipe(Argument.withDescription("TypeScript or JavaScript entry point of the program"));
 const program = Argument.String("program").pipe(Argument.withDescription("Program name"));
@@ -47,6 +47,26 @@ export function timeOf(text) {
         throw new Error(`Not a date: ${text}`);
     return ms;
 }
+export async function confirmDeletion(name, yes, interactive = process.stdin.isTTY === true) {
+    if (yes)
+        return true;
+    if (!interactive) {
+        process.stderr.write(`error[NotConfirmed]: zyrk delete ${name} deletes the program, its state, subscriptions, executions and replays: add --yes to confirm without a terminal\n`);
+        return false;
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        const answer = await prompt.question(`Delete program ${name} with its state, subscriptions, executions and replays (ctx.storage stays)? [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
 const local = (name, body) => Effect.promise(() => body().catch((error) => {
     process.stderr.write(`error[${name}]: ${error instanceof Error ? error.message : String(error)}\n`);
     process.exitCode = 1;
@@ -67,9 +87,10 @@ const exportCommand = Command.make("export", {
     "with-tx": flag("with-tx", "Export batch.tx (transaction of each trade, place in it)"),
     refresh: flag("refresh", "Download every hour again (a finished export only re-downloads the hours that were open or not sealed, or exported by an older version)"),
     totals: optionalString("totals", "Also save the totals of this mint (ctx.data.tokenTotals, tokenInfo)"),
-    quote: optionalString("quote", "Quote mint of --totals"),
+    quote: optionalString("quote", "Quote mint of --totals, or auto"),
+    compute: optionalString("compute", "Also save the answer of ctx.compute(<json plan or array of plans>), computed by the service"),
     "volume-search": optionalString("volume-search", "Also save every page of ctx.data.volumeSearch(<json params>)"),
-    rpm: Flag.Int("rpm").pipe(Flag.withDescription("At most this many requests per minute"), Flag.optional),
+    rpm: Flag.Int("rpm").pipe(Flag.withDescription("At most this many requests per minute (optional: the server allows 30 a second per account)"), Flag.optional),
     out: Flag.String("out").pipe(Flag.withAlias("o"), Flag.withDescription("Data directory (created, resumed if it exists)"), Flag.withDefault("data")),
 }, (input) => local("export", async () => {
     const url = process.env.TH_API_URL;
@@ -119,6 +140,12 @@ const exportCommand = Command.make("export", {
         await exportTotals(connection, input.out, totals, value(input.quote) ?? null);
         work = true;
     }
+    const computeText = value(input.compute);
+    if (computeText) {
+        const r = await exportCompute(connection, input.out, JSON.parse(computeText));
+        process.stderr.write(`compute: ${r.rows === null ? "an error answer (saved: the local run throws it)" : `${r.rows} row(s)`}\n`);
+        work = true;
+    }
     const volume = value(input["volume-search"]);
     if (volume) {
         const pages = await exportVolumeSearch(connection, input.out, JSON.parse(volume));
@@ -126,7 +153,7 @@ const exportCommand = Command.make("export", {
         work = true;
     }
     if (!work)
-        throw new Error("Nothing to export: --token/--wallet, --totals or --volume-search");
+        throw new Error("Nothing to export: --token/--wallet, --totals, --volume-search or --compute");
 })).pipe(Command.withDescription("Download history (one file per hour, as hosted programs see it) for zyrk dev. Resumes an interrupted export."));
 const devCommand = Command.make("dev", {
     entry,
@@ -248,6 +275,15 @@ const zyrk = Command.make("zyrk").pipe(Command.withDescription("Zyrk hosted func
     Command.make("programs", {}, () => withClient((c) => c.programs())).pipe(Command.withDescription("List the programs of the account")),
     onArgument("inspect", "Show a program", program, (c, p) => c.inspect(p)),
     onArgument("executions", "Recent executions of a program", program, (c, p) => c.executions(p)),
+    Command.make("delete", {
+        program,
+        yes: flag("yes", "Do not ask for confirmation"),
+    }, (input) => Effect.promise(() => confirmDeletion(input.program, input.yes)).pipe(Effect.flatMap((confirmed) => {
+        if (confirmed)
+            return withClient((c) => c.delete(input.program));
+        process.exitCode = 1;
+        return Effect.void;
+    }))).pipe(Command.withDescription("Delete a program and everything bound to it (state, subscriptions, executions, replays); ctx.storage stays. Asks first unless --yes")),
     onArgument("pause", "Pause a program", program, (c, p) => c.pause(p, true)),
     onArgument("resume", "Resume a program", program, (c, p) => c.pause(p, false)),
     exportCommand,

package/dist/client.d.ts

@@ -1,8 +1,8 @@
 import { Context, Effect, Layer } from "effect";
-import { Job, Json, ProgramSummary, type JobResult } from "./contracts.js";
+import { Job, Json, ProgramDeleted, ProgramSummary, type JobResult } from "./contracts.js";
 import { ApiError, ConfigError, DecodeError, ExecutionEnded, ExecutionFailed, NetworkError, WaitTimeout } from "./errors.js";
 export * from "./errors.js";
-export type { Job, JobResult, ProgramSummary } from "./contracts.js";
+export type { Job, JobResult, ProgramDeleted, ProgramSummary, } from "./contracts.js";
 import type { ReplayFeedItem, ReplayRecord, ReplayRequest } from "./sdk.js";
 export type { ReplayFeedItem, ReplayRecord, ReplayRequest } from "./sdk.js";
 export interface ClientConfig {
@@ -46,6 +46,13 @@ export interface ZyrkClientService {
     programs(): Effect.Effect<readonly ProgramSummary[], RequestError>;
     inspect(program: string): Effect.Effect<Json, RequestError>;
     pause(program: string, paused?: boolean): Effect.Effect<Json, RequestError>;
+    /**
+     * Deletes the program and everything bound to it (versions, state,
+     * subscriptions, executions, replays); what runs of it is cancelled.
+     * The account's storage stays. Fails with `program_not_found` (404) when
+     * there is no such program, also when a retried call already deleted it.
+     */
+    delete(program: string): Effect.Effect<ProgramDeleted, RequestError>;
     /** Recent executions of a program (summaries). */
     executions(program: string): Effect.Effect<Json, RequestError>;
     /** Starts an execution and returns its id. */
@@ -125,6 +132,8 @@ export declare class FunctionsClient {
     programs(signal?: AbortSignal): Promise<readonly ProgramSummary[]>;
     inspect(program: string, signal?: AbortSignal): Promise<Json>;
     pause(program: string, paused?: boolean, signal?: AbortSignal): Promise<Json>;
+    /** See {@link ZyrkClientService.delete}. */
+    delete(program: string, signal?: AbortSignal): Promise<ProgramDeleted>;
     executions(program: string, signal?: AbortSignal): Promise<Json>;
     start(program: string, input: StartInput, signal?: AbortSignal): Promise<string>;
     execution(id: string, signal?: AbortSignal): Promise<Job>;

package/dist/client.js

@@ -1,5 +1,5 @@
 import { Cause, Config, Context, Effect, Exit, Layer, Option, Redacted, Result, Schema, } from "effect";
-import { decode, Job, Json, ProgramSummary, Started, toJobResult, } from "./contracts.js";
+import { decode, Job, Json, ProgramDeleted, ProgramSummary, Started, toJobResult, } from "./contracts.js";
 import { ApiError, ConfigError, DecodeError, ExecutionEnded, ExecutionFailed, Failure, messageOf, NetworkError, WaitTimeout, } from "./errors.js";
 export * from "./errors.js";
 const ServerError = Schema.Struct({
@@ -630,6 +630,7 @@ export const make = (config) => {
         programs: () => request("GET", "programs").pipe(Effect.flatMap(decode(Schema.Array(ProgramSummary), "programs"))),
         inspect: (program) => request("GET", `programs/${segment(program)}`),
         pause: (program, paused = true) => request("POST", `programs/${segment(program)}/pause`, { paused }),
+        delete: (program) => request("DELETE", `programs/${segment(program)}`).pipe(Effect.flatMap(decode(ProgramDeleted, "delete response"))),
         executions: (program) => request("GET", `programs/${segment(program)}/executions`),
         start,
         execution,
@@ -695,6 +696,9 @@ export class FunctionsClient {
     pause(program, paused = true, signal) {
         return runPromise(this.client.pause(program, paused), signal);
     }
+    delete(program, signal) {
+        return runPromise(this.client.delete(program), signal);
+    }
     executions(program, signal) {
         return runPromise(this.client.executions(program), signal);
     }

package/dist/contracts.d.ts

@@ -277,6 +277,22 @@ export declare const ProgramSummary: Schema.Struct<{
     readonly paused: Schema.Boolean;
 }>;
 export type ProgramSummary = typeof ProgramSummary.Type;
+/** What `DELETE programs/{program}` removed (counts). */
+export declare const ProgramDeleted: Schema.Struct<{
+    readonly deleted: Schema.Boolean;
+    readonly program: Schema.String;
+    readonly removed: Schema.Struct<{
+        readonly versions: Schema.Number;
+        readonly stateKeys: Schema.Number;
+        readonly subscriptions: Schema.Number;
+        readonly executions: Schema.Number;
+        readonly cancelledExecutions: Schema.Number;
+        readonly replays: Schema.Number;
+        readonly cancelledReplays: Schema.Number;
+        readonly streamEvents: Schema.Number;
+    }>;
+}>;
+export type ProgramDeleted = typeof ProgramDeleted.Type;
 /** A schema that decodes without Effect services, so decoding is synchronous. */
 export type Decodable = Schema.Top & {
     readonly DecodingServices: never;

package/dist/contracts.js

@@ -111,6 +111,20 @@ export const ProgramSummary = Schema.Struct({
     stateVersion: Schema.Number,
     paused: Schema.Boolean,
 });
+export const ProgramDeleted = Schema.Struct({
+    deleted: Schema.Boolean,
+    program: Schema.String,
+    removed: Schema.Struct({
+        versions: Schema.Number,
+        stateKeys: Schema.Number,
+        subscriptions: Schema.Number,
+        executions: Schema.Number,
+        cancelledExecutions: Schema.Number,
+        replays: Schema.Number,
+        cancelledReplays: Schema.Number,
+        streamEvents: Schema.Number,
+    }),
+});
 export const NonNegativeInt = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0));
 export const decodeWith = (schema, options, onError) => {
     const parse = Schema.decodeUnknownResult(schema);

package/dist/export.d.ts

@@ -5,11 +5,11 @@ export interface ExportConnection {
     readonly url: string;
     /** API key (`TH_API_KEY`) of an account with hosted functions. */
     readonly apiKey: string;
-    /** At most this many requests per minute (default: as fast as the server allows). */
+    /** At most this many requests per minute (default: as fast as the server allows, 30 a second per account). Optional pacing only. */
     readonly rpm?: number;
     /** Network failures, 502, 503 and 504 tolerated in a row before giving up (default 8); another 5xx is retried once. */
     readonly maxRetries?: number;
-    /** Longest wait accepted on 429s in a row before stopping (default 5 minutes): a daily quota stops the export. */
+    /** Longest wait accepted on 429s in a row before stopping (default 5 minutes): a longer one (an older server's daily quota) stops the export. */
     readonly maxWaitMs?: number;
     readonly fetch?: typeof fetch;
     readonly signal?: AbortSignal;
@@ -85,6 +85,16 @@ export declare function exportHistory(connection: ExportConnection, out: string,
  * or the error answer saved for them (`{ error: { kind, code, message } }`).
  */
 export declare function exportTotals(connection: ExportConnection, out: string, mint: string, quote?: string | null): Promise<Json>;
+/**
+ * Saves the answer of `ctx.compute(plan)` (a plan or an array of plans), as
+ * the service computes it for a function (`POST /v1/functions/compute`, the
+ * same engine), so that the same call in a local run finds it. Relative
+ * windows (`last`, an `until` left out) are resolved now, at export. An
+ * error answer (an invalid plan, a limit) is saved as that error.
+ */
+export declare function exportCompute(connection: ExportConnection, out: string, plan: Json): Promise<{
+    rows: number | null;
+}>;
 /**
  * Saves every page of a volume search for `params`, following the
  * cursor exactly as `ctx.data.volumeSearch` does, so that the same call in

package/dist/export.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { decompressHour } from "./hourfile.js";
-import { HOUR_MS, READ_FORMAT, infoName, sha256, readId, spec as readSpec, totalsName, volumeName, } from "./local-data.js";
+import { HOUR_MS, READ_FORMAT, infoName, sha256, readId, spec as readSpec, totalsName, volumeName, computeName, } from "./local-data.js";
 import { MAX_WINDOW_MS } from "./limits.js";
 const DAY_MS = 86_400_000;
 const PART_MS = 30 * DAY_MS;
@@ -49,7 +49,7 @@ class Http {
     constructor(c) {
         this.c = c;
     }
-    async raw(path, query, keep) {
+    async raw(path, query, keep, post) {
         const f = this.c.fetch ?? fetch;
         const url = new URL(this.c.url.replace(/\/+$/, "") + path);
         for (const [k, v] of Object.entries(query))
@@ -70,7 +70,13 @@ class Http {
             let bytes;
             try {
                 response = await f(url, {
-                    headers: { authorization: `Bearer ${this.c.apiKey}` },
+                    headers: {
+                        authorization: `Bearer ${this.c.apiKey}`,
+                        ...(post !== undefined
+                            ? { "content-type": "application/json" }
+                            : {}),
+                    },
+                    ...(post !== undefined ? { method: "POST", body: post } : {}),
                     ...(this.c.signal ? { signal: this.c.signal } : {}),
                 });
                 bytes = new Uint8Array(await response.arrayBuffer());
@@ -141,8 +147,8 @@ class Http {
             throw new ExportError(`${response.status} ${code}: ${message}`, code, response.status);
         }
     }
-    async get(path, query, keep) {
-        const answer = await this.raw(path, query, keep);
+    async get(path, query, keep, post) {
+        const answer = await this.raw(path, query, keep, post);
         const text = new TextDecoder().decode(answer.bytes);
         try {
             return {
@@ -338,6 +344,7 @@ const RECORDED = new Set([
     "invalid_amount",
     "invalid_cursor",
     "usd_volume_unavailable",
+    "invalid_quote",
     "partial_coverage",
     "query_work_limit",
 ]);
@@ -393,6 +400,45 @@ export async function exportTotals(connection, out, mint, quote = null) {
     save(connection, out, ["info", infoName(mint)], info, content(info), "tokenInfo");
     return totals;
 }
+export async function exportCompute(connection, out, plan) {
+    const http = new Http(connection);
+    mkdirSync(join(out, "compute"), { recursive: true });
+    let answer;
+    try {
+        const { status, body } = await http.get("/v1/functions/compute", {}, recordable, JSON.stringify({ plan }));
+        if (status === 200)
+            answer = { ok: body };
+        else {
+            const e = body.error;
+            const retry = body.retryAfterMs;
+            answer = {
+                code: e.code,
+                error: {
+                    error: { kind: e.kind, code: e.code, message: e.message },
+                    ...(typeof retry === "number" ? { retryAfterMs: retry } : {}),
+                },
+            };
+        }
+    }
+    catch (error) {
+        if (error instanceof ExportError && error.status === 404)
+            throw new ExportError("This server does not run ctx.compute for local runs yet (it answered 404): it must be upgraded first.", "unsupported_server", 404);
+        throw error;
+    }
+    save(connection, out, ["compute", `${computeName(plan)}.json`], answer, "ok" in answer
+        ? { plan, result: answer.ok }
+        : { plan, ...answer.error }, "compute");
+    const ok = "ok" in answer ? answer.ok : null;
+    return {
+        rows: ok === null
+            ? null
+            : Array.isArray(ok)
+                ? ok.length
+                : typeof ok.length === "number"
+                    ? ok.length
+                    : null,
+    };
+}
 export async function exportVolumeSearch(connection, out, params) {
     const http = new Http(connection);
     mkdirSync(join(out, "volume"), { recursive: true });

package/dist/limits.d.ts

@@ -11,7 +11,11 @@ export declare const execLimits: {
      * reads excluded: they count in `readMs`.
      */
     readonly cpuMs: 10000;
-    /** Wall time, waits (`ctx.jobs.wait`, host operations) included. */
+    /**
+     * Wall time, waits (`ctx.jobs.wait`, host operations, timers) included.
+     * Time spent waiting for history reads (`ctx.data.*`) does not count, up
+     * to `readWaitMs`.
+     */
     readonly wallMs: 60000;
     readonly heapBytes: number;
     /** JSON arguments of a direct call or a job. */
@@ -34,6 +38,16 @@ export declare const execLimits: {
     readonly readMs: 30000;
     /** User storage bytes read plus written by one execution (`io_limit`). */
     readonly storageBytes: number;
+    /**
+     * History read wait not counted in `wallMs`, at most: an execution lasts
+     * `wallMs + readWaitMs` (15 minutes) at most.
+     */
+    readonly readWaitMs: number;
+    /**
+     * Of one history read call, at most this much is given back to `wallMs`:
+     * a read that hangs still ends at the wall limit.
+     */
+    readonly readCallWaitMs: 120000;
 };
 /** User storage (`ctx.storage`), per account. Server defaults; operators may change them. */
 export declare const storageLimits: {

package/dist/limits.js

@@ -11,6 +11,8 @@ export const execLimits = {
     hostOps: 10_000,
     readMs: 30_000,
     storageBytes: 1024 * MIB,
+    readWaitMs: 14 * 60_000,
+    readCallWaitMs: 120_000,
 };
 export const storageLimits = {
     shortQuotaBytes: 1024 * MIB,

package/dist/local-data.d.ts

@@ -106,9 +106,17 @@ export declare class LocalData {
     infoFailure(mint: string): ReadFailure | undefined;
     /** The error a volume search page answered at export, or `undefined`. */
     volumeFailure(params: readonly (readonly [string, string])[]): ReadFailure | undefined;
+    /** The answer `ctx.compute(plan)` gave at export (`zyrk export --compute`). */
+    computeResult(plan: unknown): Json | undefined;
+    /** The error `ctx.compute(plan)` answered at export, or `undefined`. */
+    computeFailure(plan: unknown): ReadFailure | undefined;
     /** A volume search page saved by the export for exactly these parameters. */
     volumePage(params: readonly (readonly [string, string])[]): Json | undefined;
 }
+/** JSON with object keys sorted at every level (the name of a plan). */
+export declare function canonical(v: unknown): string;
+/** File name of a saved compute answer. */
+export declare function computeName(plan: unknown): string;
 export declare const totalsName: (mint: string, quote: string | null) => string;
 export declare const infoName: (mint: string) => string;
 /** Parameters as the sandbox passes them (`[key, string value]`), sorted. */

package/dist/local-data.js

@@ -360,11 +360,34 @@ export class LocalData {
     volumeFailure(params) {
         return this.#failure(join("volume", `${volumeName(params)}.json`), "zyrk export --volume-search '<params>'");
     }
+    computeResult(plan) {
+        const saved = this.#json(join(this.dir, "compute", `${computeName(plan)}.json`), "zyrk export --compute '<plan>'");
+        return saved?.result;
+    }
+    computeFailure(plan) {
+        return this.#failure(join("compute", `${computeName(plan)}.json`), "zyrk export --compute '<plan>'");
+    }
     volumePage(params) {
         const saved = this.#json(join(this.dir, "volume", `${volumeName(params)}.json`), "zyrk export --volume-search '<params>'");
         return saved?.page;
     }
 }
+export function canonical(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(",")}]`;
+    if (v !== null && typeof v === "object")
+        return `{${Object.keys(v)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
+            .join(",")}}`;
+    return JSON.stringify(v) ?? "null";
+}
+export function computeName(plan) {
+    return createHash("sha256")
+        .update(canonical(plan))
+        .digest("hex")
+        .slice(0, 32);
+}
 export const totalsName = (mint, quote) => quote ? `${mint}~${quote}.json` : `${mint}.json`;
 export const infoName = (mint) => `${mint}.json`;
 export function volumeName(params) {

package/dist/local.js

@@ -6,7 +6,7 @@ import { getHeapStatistics } from "node:v8";
 import vm from "node:vm";
 import { buildProgram } from "./build.js";
 import { DELIVERY_BATCH, REPLAY_MAX_BATCH, MISSING_OPERATION_FIELDS, intervalEvents, replayEvents, } from "./local-replay.js";
-import { LocalData, ReadFailed, spec as readSpec, } from "./local-data.js";
+import { LocalData, canonical, ReadFailed, spec as readSpec, } from "./local-data.js";
 import { LocalStorage, StorageOpError, } from "./local-storage.js";
 import { accountLimits, execLimits, subscriptionLimits } from "./limits.js";
 const here = dirname(fileURLToPath(import.meta.url));
@@ -21,6 +21,20 @@ function batchReadsFromEnv() {
     }
     return on;
 }
+const COMPUTE_OUTPUT_BYTES = 64 * 2 ** 20;
+const computeLine = (r, row) => {
+    const parts = [...r.keys, ...r.measures].map((n) => {
+        const c = r.columns[n];
+        const v = c.values[row];
+        const value = c.type === "f64"
+            ? typeof v === "number" && Number.isFinite(v)
+                ? v
+                : null
+            : v;
+        return `${JSON.stringify(n)}:${JSON.stringify(value)}`;
+    });
+    return `{${parts.join(",")}}\n`;
+};
 let bootstrapText;
 export function sandboxBootstrap() {
     return (bootstrapText ??= readFileSync(join(here, "sandbox-bootstrap.js"), "utf8"));
@@ -230,6 +244,7 @@ export class LocalRunner {
             pending: 0,
             io: { bytes: 0 },
             startedAt: 0,
+            readWaitMs: 0,
             done,
             finish,
         };
@@ -370,7 +385,7 @@ export class LocalRunner {
             if (e.usage.outputBytes + size > this.limits.exec.outputBytes * e.scale)
                 throw limit("output_limit", `Result, logs and emits went over ${this.limits.exec.outputBytes * e.scale} bytes`);
             e.usage.outputBytes += size;
-            if (performance.now() - e.startedAt > this.limits.exec.wallMs)
+            if (this.#wallUsed(e) > this.limits.exec.wallMs)
                 throw limit("wall_limit", `The execution ran over ${this.limits.exec.wallMs} ms (measured locally, not preempted)`);
             if (e.cancelled)
                 throw new HostError("permission", "cancelled", "Its parent failed: the job was cancelled");
@@ -446,6 +461,38 @@ export class LocalRunner {
         };
         const fromRead = (f) => new HostError(kindOfSdkCode(f.code), f.code, f.message, f.retryAfterMs);
         const guestJson = (v) => realm.JSON.parse(JSON.stringify(v) ?? "null");
+        const computeOutputs = new Map();
+        let computeNext = 0;
+        const computeSummary = (r) => ({
+            length: r.length,
+            keys: r.keys,
+            measures: r.measures,
+            coverage: r.coverage,
+            complete: r.complete,
+            skipped: r.skipped,
+            stats: r.stats,
+        });
+        const computeObject = (r) => {
+            const o = guestJson(computeSummary(r));
+            const columns = new realm.Object();
+            for (const n of [...r.keys, ...r.measures]) {
+                const c = r.columns[n];
+                columns[n] =
+                    c.type === "f64"
+                        ? realm.Float64Array.from(c.values.map((v) => v === "NaN"
+                            ? NaN
+                            : v === "Infinity"
+                                ? Infinity
+                                : v === "-Infinity"
+                                    ? -Infinity
+                                    : Number(v)))
+                        : c.type === "int"
+                            ? realm.Array.from(c.values.map((v) => (v === null ? null : BigInt(String(v)))))
+                            : realm.Array.from(c.values);
+            }
+            o.columns = columns;
+            return o;
+        };
         const ms = (v) => typeof v === "number" && Number.isFinite(v) && Math.abs(v) < 9e15
             ? Math.trunc(v)
             : undefined;
@@ -472,6 +519,9 @@ export class LocalRunner {
                 wf.readBytes > this.limits.account.workflowReadBytes)
                 throw readLimit();
         };
+        const waited = (t0) => {
+            e.readWaitMs += Math.min(performance.now() - t0, this.limits.exec.readCallWaitMs);
+        };
         const data = () => {
             if (!this.data)
                 throw sdkError(program("local_data_missing", "No data directory: export history with zyrk export, then pass --data (or { data })."));
@@ -480,6 +530,7 @@ export class LocalRunner {
         const saved = (answer, failure, missing) => {
             let value;
             let failed;
+            const t0 = performance.now();
             try {
                 value = answer();
                 failed = value === undefined ? failure() : undefined;
@@ -489,6 +540,9 @@ export class LocalRunner {
                     throw sdkError(fromRead(error.failure));
                 throw error;
             }
+            finally {
+                waited(t0);
+            }
             if (failed)
                 throw sdkError(fromRead(failed));
             if (value === undefined)
@@ -541,6 +595,7 @@ export class LocalRunner {
                 }
                 finally {
                     e.usage.readMs += performance.now() - t0;
+                    waited(t0);
                     sample();
                 }
                 if (hour === null)
@@ -567,6 +622,63 @@ export class LocalRunner {
                     throw sdkError(program("invalid_argument", "Expected a mint address"));
                 return saved(() => data().info(mint), () => data().infoFailure(mint), `No exported info for ${mint} (exports by older versions saved only its totals): zyrk export --totals ${mint}`);
             },
+            computeAsk: () => realm.Promise.resolve(),
+            compute: (text, toStorage) => {
+                readAllowed();
+                e.usage.readCalls++;
+                let plan;
+                try {
+                    plan = JSON.parse(String(text));
+                }
+                catch {
+                    throw sdkError(program("invalid_plan", "The plan is not JSON"));
+                }
+                const answer = saved(() => data().computeResult(plan), () => data().computeFailure(plan), `No exported result for this plan: zyrk export --compute '${canonical(plan)}'`);
+                if (toStorage === true) {
+                    if (computeOutputs.size > 0)
+                        throw sdkError(program("invalid_argument", "One ctx.compute output at a time per execution: await the one being written first"));
+                    if (Array.isArray(answer))
+                        throw sdkError(program("invalid_plan", "output writes the result of one plan"));
+                    const result = answer;
+                    let bytes = 0;
+                    for (let row = 0; row < result.length; row++)
+                        bytes += Buffer.byteLength(computeLine(result, row), "utf8");
+                    if (bytes > COMPUTE_OUTPUT_BYTES)
+                        throw sdkError(limit("compute_result_limit", `the result is ${Math.ceil(bytes / 2 ** 20)} MiB of JSON lines (${result.length} rows), more than the ${COMPUTE_OUTPUT_BYTES / 2 ** 20} MiB of one storage object: add a limit, a top or a having, group less finely, or split the range into several calls`));
+                    const handle = computeNext++;
+                    computeOutputs.set(handle, {
+                        result: answer,
+                        row: 0,
+                    });
+                    return guestJson({
+                        handle,
+                        summary: computeSummary(answer),
+                    });
+                }
+                return Array.isArray(answer)
+                    ? realm.Array.from(answer.map((a) => computeObject(a)))
+                    : computeObject(answer);
+            },
+            computeChunk: (handle) => {
+                const o = computeOutputs.get(Number(handle));
+                if (!o)
+                    throw sdkError(program("invalid_argument", "Unknown compute output"));
+                const r = o.result;
+                if (o.row >= r.length)
+                    return null;
+                let text = "";
+                while (o.row < r.length && text.length < 4 * 1024 * 1024 - 64 * 1024) {
+                    text += computeLine(r, o.row);
+                    o.row++;
+                }
+                const bytes = Buffer.from(text, "utf8");
+                const out = new realm.Uint8Array(bytes.length);
+                out.set(bytes);
+                return out;
+            },
+            computeDrop: (handle) => {
+                computeOutputs.delete(Number(handle));
+            },
             volume: (text) => {
                 readAllowed();
                 e.usage.readCalls++;
@@ -602,8 +714,13 @@ export class LocalRunner {
             },
         };
     }
+    #wallUsed(e) {
+        return (performance.now() -
+            e.startedAt -
+            Math.min(e.readWaitMs, this.limits.exec.readWaitMs));
+    }
     #checkWall(e) {
-        if (performance.now() - e.startedAt > this.limits.exec.wallMs) {
+        if (this.#wallUsed(e) > this.limits.exec.wallMs) {
             e.fatal ??= limit("wall_limit", `The execution ran over ${this.limits.exec.wallMs} ms`);
             throw e.fatal;
         }
@@ -795,7 +912,7 @@ export class LocalRunner {
                 });
                 if (this.#waiting >= account.parallelExecutions - 1)
                     throw limit("job_wait_limit", `At most ${account.parallelExecutions - 1} executions wait at once`);
-                const left = this.limits.exec.wallMs - (performance.now() - e.startedAt);
+                const left = this.limits.exec.wallMs - this.#wallUsed(e);
                 const timeout = Math.max(0, Math.min(typeof a.timeout_ms === "number" ? a.timeout_ms : left, left));
                 this.#waiting++;
                 let timer;

package/dist/sandbox-bootstrap.js

@@ -427,6 +427,65 @@
     long: storageArea("long"),
     durable: storageArea("durable")
   });
+  const computeAreas = ["short", "long", "durable"];
+  let outputTurn = PromiseCtor.resolve();
+  const compute = async (plan, options) => {
+    if (plan === null || typeof plan !== "object")
+      throw fail("invalid_plan", "Expected a plan object (or an array of plans)");
+    let output;
+    if (options !== void 0 && options !== null) {
+      if (typeOf(options) !== "object") throw fail("invalid_argument", "Expected options { output }");
+      for (const k of keys(options))
+        if (k !== "output") throw fail("invalid_argument", "Unknown compute option: " + k);
+      output = options.output;
+      if (output !== void 0 && (typeOf(output) !== "object" || !computeAreas.includes(output.area) || typeof output.key !== "string"))
+        throw fail("invalid_argument", 'output is { area: "short" | "long" | "durable", key }');
+    }
+    let text;
+    try {
+      text = stringify(plan);
+    } catch {
+      throw fail("invalid_plan", "The plan is not JSON (write integers beyond 2^53 as decimal strings)");
+    }
+    await N.computeAsk(text);
+    if (output === void 0) return N.compute(text, false);
+    const before = outputTurn;
+    let release;
+    outputTurn = new PromiseCtor((resolve) => {
+      release = resolve;
+    });
+    try {
+      await before;
+      return await computeOutput(text, output);
+    } finally {
+      release();
+    }
+  };
+  const computeOutput = async (text, output) => {
+    const r = N.compute(text, true);
+    let w;
+    try {
+      w = await storage[output.area].writer(output.key, { contentType: "application/x-ndjson" });
+      let bytes = 0;
+      for (; ; ) {
+        const chunk = N.computeChunk(r.handle);
+        if (chunk === null) break;
+        bytes += chunk.length;
+        await w.write(chunk);
+      }
+      const head2 = await w.close();
+      return freeze({
+        ...r.summary,
+        output: freeze({ area: output.area, key: output.key, rows: r.summary.length, bytes, etag: head2.etag })
+      });
+    } catch (e) {
+      if (w) await w.abort().catch(() => {
+      });
+      throw e;
+    } finally {
+      N.computeDrop(r.handle);
+    }
+  };
   const start = (functionName, argsText, executionText) => {
     const p = program();
     let depth = 0;
@@ -487,6 +546,7 @@
         continue: (args) => call({ Continue: { args } })
       }),
       storage,
+      compute,
       subscriptions: freeze({
         set: (name, subscription) => call({ Subscribe: { name, subscription } }),
         remove: (name) => call({ Unsubscribe: { name } }),

package/dist/sdk.d.ts

@@ -388,6 +388,12 @@ export type TokenMetadata = {
     readonly quoteName: string | null;
     readonly quoteSymbol: string | null;
     readonly quoteUri: string | null;
+    /**
+     * Decimals of `quoteMint`: the row's, else 9 for SOL and 6 for USDC, else
+     * those of the quote table (rows sent before 2026-10-29 18:15 UTC lack
+     * them), else `null` (absent from metadata saved by older exports).
+     */
+    readonly quoteDecimals?: number | null;
     /** Time, slot and signature of the row the values come from. */
     readonly asOfMs: number | null;
     readonly slot: number | null;
@@ -930,6 +936,189 @@ export interface StorageArea {
     putJSON(key: string, value: JsonInput, options?: Omit<StoragePutOptions, "contentType">): Promise<StorageObjectHead>;
     writer(key: string, options?: StoragePutOptions): Promise<StorageWriter>;
 }
+/** Milliseconds, or text such as `"500ms"`, `"30s"`, `"15m"`, `"6h"`, `"30d"`. */
+export type ComputeDuration = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
+/** `[since, until)` in ms; `until` defaults to the call's time. */
+export type ComputeWindow = {
+    readonly since: number;
+    readonly until?: number;
+} | {
+    readonly last: ComputeDuration;
+    readonly until?: number;
+};
+/** Fields of a trade a filter or a measure reads. */
+export type ComputeField = "side" | "protocol" | "token" | "trader" | "quoteMint" | "timeMs" | "ageMs" | "quoteRaw" | "tokenRaw" | "quoteAmount" | "tokenAmount" | "execPrice" | "isCreator" | "marketFlags" | "orderFlags";
+/** Fields measured by `sum`, `min`, `max`, `avg`, `first`, `last`, `anchor`, `asOf`. */
+export type ComputeNumericField = "timeMs" | "ageMs" | "quoteRaw" | "tokenRaw" | "quoteAmount" | "tokenAmount" | "execPrice";
+type ComputeValue = string | number | boolean;
+/** A comparison of one field: a value (equality), or operators (all must hold). */
+export type ComputeCondition = ComputeValue | {
+    readonly eq?: ComputeValue;
+    readonly ne?: ComputeValue;
+    readonly gt?: number | string;
+    readonly gte?: number | string;
+    readonly lt?: number | string;
+    readonly lte?: number | string;
+    readonly in?: readonly ComputeValue[];
+    readonly notIn?: readonly ComputeValue[];
+    /** Flag fields (`marketFlags`, `orderFlags`): bits of the mask set. */
+    readonly hasAll?: number;
+    readonly hasAny?: number;
+    readonly hasNone?: number;
+};
+/**
+ * A filter: every field listed must pass (`and`), with `and`, `or`, `not`
+ * to combine. In `where`, the fields of a trade (and `"<stage>.<measure>"`);
+ * in `having`, the measures and keys of a group. A comparison with an
+ * unknown value (no trader, a creation not seen, a missing stage value) is
+ * false, `ne` and `notIn` included.
+ */
+export interface ComputeFilter {
+    readonly and?: readonly ComputeFilter[];
+    readonly or?: readonly ComputeFilter[];
+    readonly not?: ComputeFilter;
+    readonly [field: string]: ComputeCondition | ComputeFilter | readonly ComputeFilter[] | undefined;
+}
+export type ComputeKey = "token" | "trader" | "quoteMint" | "side" | "protocol"
+/** `floor(timeMs / width) * width`. */
+ | {
+    readonly time: ComputeDuration;
+}
+/** `floor(ageMs / width) * width` (tokens whose creation is known). */
+ | {
+    readonly age: ComputeDuration;
+};
+type MeasureOptions = {
+    /** Only the trades that pass it. */
+    readonly where?: ComputeFilter;
+    /** Plans with `anchors`: the token's trades in `[anchor + from, anchor + to)` ms. */
+    readonly window?: readonly [number, number];
+};
+export type ComputeMeasure = ({
+    readonly count: true;
+} & MeasureOptions) | ({
+    readonly countDistinct: "token" | "trader" | "quoteMint";
+} & MeasureOptions) | ({
+    readonly sum: ComputeNumericField;
+} & MeasureOptions) | ({
+    readonly min: ComputeNumericField;
+} & MeasureOptions) | ({
+    readonly max: ComputeNumericField;
+} & MeasureOptions) | ({
+    readonly avg: ComputeNumericField;
+} & MeasureOptions)
+/** In the token's trade sequence (see the docs). */
+ | ({
+    readonly first: ComputeNumericField;
+} & MeasureOptions) | ({
+    readonly last: ComputeNumericField;
+} & MeasureOptions)
+/** `Number(a) / Number(b)` of two other measures. */
+ | {
+    readonly ratio: readonly [string, string];
+}
+/** Plans with `anchors`: a field of the anchor trade. */
+ | {
+    readonly anchor: ComputeNumericField;
+}
+/**
+ * Plans with `anchors`: `field` of the token's trade as of `anchor +
+ * offsetMs` (the last at or before it; with `direction: "after"`, the
+ * first at or after it), within `withinMs` (default and at most 1 h). An
+ * array of offsets gives one column each, `"<name>@<offset>"`.
+ */
+ | ({
+    readonly asOf: ComputeNumericField;
+    readonly offsetMs: number | readonly number[];
+    readonly direction?: "before" | "after";
+    readonly withinMs?: number;
+} & Omit<MeasureOptions, "window">);
+export interface ComputePlan {
+    readonly range: ComputeWindow;
+    /** Only these mints (1 to 10 000). */
+    readonly tokens?: readonly Address[];
+    /** Only the tokens created in this window (creations seen in its hours). */
+    readonly created?: ComputeWindow;
+    /** `"SOL"` (default), a quote mint, `"auto"` (per token, as `tokenTotals`) or `"any"`. */
+    readonly quote?: "SOL" | "auto" | "any" | Address;
+    readonly where?: ComputeFilter;
+    readonly groupBy?: readonly ComputeKey[];
+    /** 1 to 16 named measures; results list them in name order. */
+    readonly measures: Readonly<Record<string, ComputeMeasure>>;
+    readonly having?: ComputeFilter;
+    /** The `n` groups with the largest `by`, per partition of the `per` keys. */
+    readonly top?: {
+        readonly by: string;
+        readonly n: number;
+        readonly per?: readonly string[];
+    };
+    readonly orderBy?: readonly (string | {
+        readonly by: string;
+        readonly desc?: boolean;
+    })[];
+    readonly limit?: number;
+    /** Accept a window not fully covered, or rejected operations. */
+    readonly allowPartial?: boolean;
+    /** Stages: measures per token, read in `where` as `"<stage>.<measure>"`. */
+    readonly with?: Readonly<Record<string, {
+        readonly where?: ComputeFilter;
+        readonly measures: Readonly<Record<string, ComputeMeasure>>;
+        readonly having?: ComputeFilter;
+    }>>;
+    /**
+     * One row per anchor: the first trade, in its token's sequence, of each
+     * group of `by` (with `token`) that passes `where`. Measures then read it
+     * (`anchor`) and its token's trades around it (`asOf`, `window`).
+     */
+    readonly anchors?: {
+        readonly by: readonly ComputeKey[];
+        readonly where?: ComputeFilter;
+        readonly pick?: "first";
+    };
+}
+/** A column of a result: addresses and names, numbers, or exact integers. */
+export type ComputeColumn = readonly (string | null)[] | Float64Array | readonly (bigint | null)[];
+export interface ComputeStats {
+    readonly hours: number;
+    readonly derivedHours: number;
+    readonly sealedHours: number;
+    readonly openHours: number;
+    readonly passes: number;
+    readonly trades: number;
+    readonly groups: number;
+    /** Server time of the call, every thread (the history reading; not your CPU). */
+    readonly cpuMs: number;
+    readonly wallMs: number;
+}
+interface ComputeSummary {
+    readonly length: number;
+    /** Key columns, in `groupBy` order. */
+    readonly keys: readonly string[];
+    /** Measure columns, in name order. */
+    readonly measures: readonly string[];
+    readonly coverage: Json;
+    /** Covered, and no rejected operation counted. */
+    readonly complete: boolean;
+    /** Operations of the tokens read that normalization rejects, in the range. */
+    readonly skipped: number;
+    readonly stats: ComputeStats;
+}
+export interface ComputeResult extends ComputeSummary {
+    /** One column per key and measure, `length` values each. */
+    readonly columns: Readonly<Record<string, ComputeColumn>>;
+}
+/** A result written to storage (`output`): JSON lines, one object per row. */
+export interface ComputeOutput extends ComputeSummary {
+    readonly output: {
+        readonly area: "short" | "long" | "durable";
+        readonly key: string;
+        readonly rows: number;
+        readonly bytes: number;
+        readonly etag: string;
+    };
+}
+/** The rows of a result as objects (keys and measures by name). */
+export declare function computeRows(r: ComputeResult): Record<string, string | number | bigint | null>[];
 export interface Context {
     readonly execution: ExecutionInfo;
     readonly data: {
@@ -943,10 +1132,13 @@ export interface Context {
         /**
          * Volume of a token since its creation (`cumulativeRaw`, `buyRaw`,
          * `sellRaw`, `buys`, `sells`, `sinceCreation.complete`, `coverage`), its
-         * `creation` and `metadata`, as JSON.
+         * `creation` and `metadata`, as JSON. Amounts are in `quoteMint` at
+         * `quoteDecimals`; without `quote`: SOL; `quote: "auto"`: SOL unless the
+         * token trades in other quotes only (then its most traded one; `quotes`
+         * lists them all).
          */
         tokenTotals(mint: Address, options?: {
-            quote?: Address;
+            quote?: Address | "auto";
         }): Promise<Json>;
         /**
          * Latest known metadata and the creation, at most two blocks read (no
@@ -990,6 +1182,22 @@ export interface Context {
      * after the last write), `long` (500 MiB, 7 days after the last write) and
      * `durable` (50 MiB, never expires).
      */
+    /**
+     * Runs a plan (or up to 8 plans over one read) natively over the
+     * history: answers columns, or with `output` writes the rows to storage
+     * as JSON lines and answers a summary. Errors: `invalid_plan`,
+     * `invalid_window`, `partial_coverage`, `compute_result_limit`,
+     * `compute_memory_limit`, `compute_limit`, `compute_overflow`, and those of
+     * history reads.
+     */
+    compute(plan: ComputePlan): Promise<ComputeResult>;
+    compute(plans: readonly ComputePlan[]): Promise<ComputeResult[]>;
+    compute(plan: ComputePlan, options: {
+        readonly output: {
+            readonly area: "short" | "long" | "durable";
+            readonly key: string;
+        };
+    }): Promise<ComputeOutput>;
     readonly storage: {
         readonly short: StorageArea;
         readonly long: StorageArea;

package/dist/sdk.js

@@ -73,6 +73,18 @@ export function isCompletion(args) {
         args.kind === "completion" &&
         typeof args.executionId === "string");
 }
+export function computeRows(r) {
+    const names = [...r.keys, ...r.measures];
+    const out = [];
+    for (let i = 0; i < r.length; i++) {
+        const row = {};
+        for (const n of names)
+            row[n] =
+                r.columns[n][i] ?? null;
+        out.push(row);
+    }
+    return out;
+}
 export const SDK_MARKER = "__zyrkSdk";
 export const SDK_VERSION = "0.2";
 export function defineProgram(program) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johannc-dev/zyrk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "SDK and CLI for Zyrk hosted functions",
   "license": "UNLICENSED",
   "publishConfig": {