@johannc-dev/zyrk 0.0.0-stage → 0.2.1

package/dist/export.d.ts

@@ -0,0 +1,96 @@
+import { type ReadMeta } from "./local-data.js";
+import type { Json, VolumeSearchParams } from "./sdk.js";
+export interface ExportConnection {
+    /** Gateway URL (`TH_API_URL`). */
+    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). */
+    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. */
+    readonly maxWaitMs?: number;
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: ExportProgress) => void;
+    /**
+     * Hours that may still change (open, not sealed), files downloaded again,
+     * errors saved as the answer of a call.
+     */
+    readonly onWarning?: (message: string) => void;
+}
+export interface ExportProgress {
+    readonly read: string;
+    readonly hour: number | null;
+    readonly hours: number;
+    readonly done: boolean;
+    readonly bytes: number;
+}
+export interface ExportRead {
+    readonly scope: "token" | "wallet";
+    readonly key: string;
+    readonly sinceMs: number;
+    readonly untilMs: number;
+    readonly side?: "any" | "buy" | "sell";
+    readonly withSignatures?: boolean;
+    readonly withMarket?: boolean;
+    readonly withEvents?: boolean;
+    readonly withOrder?: boolean;
+    readonly withTx?: boolean;
+    /** Download every hour again, even those of a finished export. */
+    readonly refresh?: boolean;
+}
+export declare class ExportError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    readonly name = "ExportError";
+    constructor(message: string, code: string, status?: number | undefined);
+}
+export interface ExportSummary {
+    readonly reads: readonly ReadMeta[];
+    readonly requests: number;
+    /** Compressed bytes written. */
+    readonly bytes: number;
+}
+/** `[since, until)` in parts of at most 30 days, ending on UTC day boundaries. */
+export declare function parts(sinceMs: number, untilMs: number): [number, number][];
+/** Meta of an export answer. */
+interface HourMeta {
+    readonly format?: string;
+    readonly coverage?: ReadMeta["coverage"];
+    readonly batch?: {
+        hour: number;
+        zstdBytes: number;
+    } | null;
+    readonly resumeAfterHour?: number | null;
+    readonly done?: boolean;
+}
+/** `"ZXH1" | u32 LE meta length | meta JSON | exported hour`. */
+export declare function parseFrame(bytes: Uint8Array): {
+    meta: HourMeta;
+    file: Uint8Array;
+};
+/**
+ * The first hour to download again in a finished export: an hour that was
+ * open (`live`) or not sealed yet when it was exported may have changed.
+ * `null`: nothing to refresh.
+ */
+export declare function staleFrom(meta: ReadMeta, dir: string): number | null;
+/** Exports one read (cut into parts of at most 30 days). Resumes an interrupted export. */
+export declare function exportHistory(connection: ExportConnection, out: string, read: ExportRead): Promise<ExportSummary>;
+/**
+ * Saves the totals of a mint for `ctx.data.tokenTotals`, and its info for
+ * `ctx.data.tokenInfo`, as hosted programs receive them. Returns the totals,
+ * 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 every page of a volume search for `params`, following the
+ * cursor exactly as `ctx.data.volumeSearch` does, so that the same call in
+ * a local run finds each page. A page answered by an error (an invalid
+ * parameter...) is saved as that error, and ends the search, as it does in a
+ * hosted call.
+ */
+export declare function exportVolumeSearch(connection: ExportConnection, out: string, params: VolumeSearchParams): Promise<number>;
+export {};

package/dist/export.js

@@ -0,0 +1,422 @@
+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 { MAX_WINDOW_MS } from "./limits.js";
+const DAY_MS = 86_400_000;
+const PART_MS = 30 * DAY_MS;
+export class ExportError extends Error {
+    code;
+    status;
+    name = "ExportError";
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export function parts(sinceMs, untilMs) {
+    if (!(untilMs > sinceMs) || sinceMs < 0)
+        throw new ExportError("--until must be after --since", "invalid_window");
+    const out = [];
+    for (let a = sinceMs; a < untilMs;) {
+        const b = Math.min(untilMs, Math.floor(a / DAY_MS) * DAY_MS + PART_MS);
+        out.push([a, b]);
+        a = b;
+    }
+    return out;
+}
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(signal.reason);
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(t);
+        reject(signal.reason);
+    }, { once: true });
+});
+const writeAtomic = (file, data) => {
+    const tmp = `${file}.tmp-${process.pid}`;
+    writeFileSync(tmp, data);
+    renameSync(tmp, file);
+};
+const MAX_BUSY_ATTEMPTS = 12;
+const MAX_SERVER_ERRORS = 1;
+class Http {
+    c;
+    requests = 0;
+    #last = 0;
+    constructor(c) {
+        this.c = c;
+    }
+    async raw(path, query, keep) {
+        const f = this.c.fetch ?? fetch;
+        const url = new URL(this.c.url.replace(/\/+$/, "") + path);
+        for (const [k, v] of Object.entries(query))
+            url.searchParams.set(k, v);
+        let failures = 0;
+        let serverErrors = 0;
+        let busy = 0;
+        let waited = 0;
+        for (;;) {
+            if (this.c.rpm) {
+                const gap = 60_000 / this.c.rpm - (Date.now() - this.#last);
+                if (gap > 0)
+                    await sleep(gap, this.c.signal);
+            }
+            this.#last = Date.now();
+            this.requests++;
+            let response;
+            let bytes;
+            try {
+                response = await f(url, {
+                    headers: { authorization: `Bearer ${this.c.apiKey}` },
+                    ...(this.c.signal ? { signal: this.c.signal } : {}),
+                });
+                bytes = new Uint8Array(await response.arrayBuffer());
+            }
+            catch (error) {
+                if (this.c.signal?.aborted)
+                    throw error;
+                if (++failures > (this.c.maxRetries ?? 8))
+                    throw new ExportError(`Network error on ${url.pathname}: ${String(error)}`, "network");
+                await sleep(Math.min(30_000, 500 * 2 ** failures), this.c.signal);
+                continue;
+            }
+            const contentType = response.headers.get("content-type") ?? "";
+            if (response.ok)
+                return { status: response.status, contentType, bytes };
+            let body = null;
+            try {
+                body = JSON.parse(new TextDecoder().decode(bytes));
+            }
+            catch {
+                body = null;
+            }
+            if (keep?.(response.status, body))
+                return { status: response.status, contentType, bytes };
+            const err = body?.error;
+            const code = typeof err === "string"
+                ? err
+                : typeof err?.code === "string"
+                    ? err.code
+                    : `http_${response.status}`;
+            const message = err?.message ?? code;
+            const after = response.headers.get("retry-after");
+            const header = after === null ? Number.NaN : Number(after);
+            const bodyRetry = body
+                ?.retryAfterMs;
+            const retryMs = typeof bodyRetry === "number"
+                ? bodyRetry
+                : Number.isFinite(header) && header >= 0
+                    ? header * 1000
+                    : undefined;
+            if (response.status === 429) {
+                const maxWait = this.c.maxWaitMs ?? 300_000;
+                const asked = retryMs ?? 60_000;
+                if (asked > maxWait)
+                    throw new ExportError(`${code}: ${message} Retry after ${Math.round(asked / 1000)} s: run the same command again then, the export resumes where it stopped.`, code, 429);
+                const wait = Math.max(asked, Math.min(30_000, 1000 * 2 ** busy));
+                if (++busy >= MAX_BUSY_ATTEMPTS || waited + wait > maxWait)
+                    throw new ExportError(`${code}: ${message} The server answered 429 ${busy} times in a row (${Math.round(waited / 1000)} s): run the same command again later, the export resumes where it stopped.`, code, 429);
+                waited += wait;
+                await sleep(wait, this.c.signal);
+                continue;
+            }
+            if (response.status >= 500 &&
+                response.status !== 502 &&
+                response.status !== 503 &&
+                response.status !== 504) {
+                if (++serverErrors > MAX_SERVER_ERRORS)
+                    throw new ExportError(`${response.status} ${code}: ${message}`, code, response.status);
+                await sleep(Math.min(30_000, 500 * 2 ** serverErrors), this.c.signal);
+                continue;
+            }
+            if (response.status >= 500 && code !== "history_timeout") {
+                if (++failures > (this.c.maxRetries ?? 8))
+                    throw new ExportError(`${response.status} ${code}: ${message}`, code, response.status);
+                await sleep(retryMs ?? Math.min(30_000, 500 * 2 ** failures), this.c.signal);
+                continue;
+            }
+            throw new ExportError(`${response.status} ${code}: ${message}`, code, response.status);
+        }
+    }
+    async get(path, query, keep) {
+        const answer = await this.raw(path, query, keep);
+        const text = new TextDecoder().decode(answer.bytes);
+        try {
+            return {
+                status: answer.status,
+                body: text ? JSON.parse(text) : null,
+            };
+        }
+        catch {
+            throw new ExportError(`${path}: the answer is not JSON`, "decode");
+        }
+    }
+}
+export function parseFrame(bytes) {
+    const magic = String.fromCharCode(...bytes.subarray(0, 4));
+    if (bytes.length < 8 || magic !== "ZXH1")
+        throw new ExportError("Unexpected answer from the history route (not an export frame)", "decode");
+    const n = new DataView(bytes.buffer, bytes.byteOffset).getUint32(4, true);
+    if (8 + n > bytes.length)
+        throw new ExportError("Truncated answer of the history route", "decode");
+    const meta = JSON.parse(new TextDecoder().decode(bytes.subarray(8, 8 + n)));
+    if (meta.format !== "zyrk-hour/2")
+        throw new ExportError(`Unexpected answer from the history route (format ${String(meta.format)}): update the SDK`, "decode");
+    const file = bytes.subarray(8 + n);
+    if (meta.batch && file.length !== meta.batch.zstdBytes)
+        throw new ExportError("Truncated answer of the history route", "decode");
+    return { meta, file };
+}
+function loadMeta(file) {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function cleanTemporaries(dir) {
+    for (const name of readdirSync(dir))
+        if (/\.tmp-\d+$/.test(name))
+            rmSync(join(dir, name), { force: true });
+}
+export function staleFrom(meta, dir) {
+    const sealed = meta.coverage?.sealedUntilMs ?? 0;
+    let from = sealed < meta.untilMs || meta.coverage?.preparing
+        ? Math.floor(Math.max(sealed, meta.sinceMs) / HOUR_MS) - 1
+        : null;
+    for (const hour of meta.hours) {
+        if (from !== null && hour >= from)
+            break;
+        let live = false;
+        try {
+            const { header } = decompressHour(readFileSync(join(dir, `${hour}.zhb`)));
+            live =
+                header.source === "live" || (header.market && !header.virtualSides);
+        }
+        catch {
+            live = true;
+        }
+        if (live) {
+            from = hour;
+            break;
+        }
+    }
+    return from;
+}
+async function exportPart(http, out, s, sinceMs, untilMs, progress, refresh, onProgress, onWarning) {
+    const id = readId(s, sinceMs, untilMs);
+    const dir = join(out, "reads", id);
+    mkdirSync(dir, { recursive: true });
+    cleanTemporaries(dir);
+    const file = join(dir, "read.json");
+    const fresh = {
+        format: READ_FORMAT,
+        ...s,
+        sinceMs,
+        untilMs,
+        coverage: null,
+        afterHour: null,
+        done: false,
+        hours: [],
+        hashes: {},
+        updatedAt: new Date().toISOString(),
+    };
+    let meta = refresh ? fresh : (loadMeta(file) ?? fresh);
+    if (meta.done) {
+        const from = staleFrom(meta, dir);
+        if (from !== null) {
+            onWarning?.(`${id}: hours from ${new Date(from * HOUR_MS).toISOString()} were open or not sealed when exported, or exported by an older version; downloading them again`);
+            const hours = meta.hours.filter((h) => h < from);
+            meta = {
+                ...meta,
+                done: false,
+                afterHour: hours.length ? from - 1 : null,
+                hours,
+                hashes: Object.fromEntries(Object.entries(meta.hashes ?? {}).filter(([h]) => Number(h) < from)),
+            };
+        }
+    }
+    const save = () => writeAtomic(file, JSON.stringify(meta, null, 1));
+    save();
+    while (!meta.done) {
+        const query = {
+            since_ms: String(sinceMs),
+            until_ms: String(untilMs),
+            side: s.side,
+            allow_partial: "true",
+            with_signatures: String(s.withSignatures),
+            with_market: String(s.withMarket),
+            with_events: String(s.withEvents),
+            with_order: String(s.withOrder),
+            with_tx: String(!!s.withTx),
+        };
+        if (meta.afterHour !== null)
+            query.after_hour = String(meta.afterHour);
+        const answer = await http.raw(`/v1/functions/history/${s.scope}/${encodeURIComponent(s.key)}`, query);
+        const { meta: m, file: bytes } = parseFrame(answer.bytes);
+        const coverage = m.coverage ?? meta.coverage;
+        if (!m.batch) {
+            if (typeof m.resumeAfterHour === "number") {
+                meta = { ...meta, coverage, afterHour: m.resumeAfterHour };
+                save();
+                continue;
+            }
+            const sealed = coverage?.sealedUntilMs ?? 0;
+            meta = {
+                ...meta,
+                coverage,
+                done: true,
+                updatedAt: new Date().toISOString(),
+            };
+            save();
+            if (sealed < untilMs)
+                onWarning?.(`${id}: history after ${new Date(sealed).toISOString()} was not sealed yet; run zyrk export again later to get its final hours`);
+            onProgress?.({
+                read: id,
+                hour: null,
+                hours: meta.hours.length,
+                done: true,
+                bytes: progress.bytes,
+            });
+            break;
+        }
+        const { hour } = m.batch;
+        let header;
+        try {
+            header = decompressHour(bytes).header;
+        }
+        catch (e) {
+            throw new ExportError(`Hour ${hour}: ${e.message}`, "decode");
+        }
+        if (header.hour !== hour)
+            throw new ExportError(`Hour ${hour}: inconsistent file`, "decode");
+        if (meta.afterHour !== null && hour <= meta.afterHour)
+            throw new ExportError(`Hour ${hour} came twice`, "decode");
+        writeAtomic(join(dir, `${hour}.zhb`), bytes);
+        progress.bytes += bytes.length;
+        meta = {
+            ...meta,
+            coverage,
+            afterHour: hour,
+            hours: [...meta.hours, hour],
+            hashes: { ...meta.hashes, [String(hour)]: sha256(bytes) },
+            updatedAt: new Date().toISOString(),
+        };
+        save();
+        onProgress?.({
+            read: id,
+            hour,
+            hours: meta.hours.length,
+            done: false,
+            bytes: progress.bytes,
+        });
+    }
+    return meta;
+}
+export async function exportHistory(connection, out, read) {
+    const http = new Http(connection);
+    const s = readSpec(read);
+    const progress = { bytes: 0 };
+    const reads = [];
+    for (const [a, b] of parts(read.sinceMs, read.untilMs)) {
+        if (b - a > MAX_WINDOW_MS)
+            throw new ExportError("part too long", "bug");
+        reads.push(await exportPart(http, out, s, a, b, progress, !!read.refresh, connection.onProgress, connection.onWarning));
+    }
+    return { reads, requests: http.requests, bytes: progress.bytes };
+}
+const RECORDED = new Set([
+    "invalid_window",
+    "invalid_parameter",
+    "invalid_limit",
+    "invalid_amount",
+    "invalid_cursor",
+    "usd_volume_unavailable",
+    "partial_coverage",
+    "query_work_limit",
+]);
+const recordable = (status, body) => {
+    const e = body?.error;
+    return (status === 400 &&
+        typeof e === "object" &&
+        e !== null &&
+        typeof e.kind === "string" &&
+        typeof e.code === "string" &&
+        typeof e.message === "string" &&
+        RECORDED.has(e.code));
+};
+async function getNew(http, path, query, what) {
+    try {
+        const { status, body } = await http.get(path, query, recordable);
+        if (status !== 400)
+            return { ok: body };
+        const e = body.error;
+        const retry = body.retryAfterMs;
+        return {
+            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 export ${what} yet (it answered 404): it must be upgraded first. Trades (--token, --wallet) export as before.`, "unsupported_server", 404);
+        throw error;
+    }
+}
+function save(connection, out, [dir, name], answer, content, call) {
+    const ok = join(out, dir, name);
+    const failed = join(out, "errors", dir, name);
+    const [file, other] = "ok" in answer ? [ok, failed] : [failed, ok];
+    mkdirSync(dirname(file), { recursive: true });
+    writeAtomic(file, JSON.stringify(content));
+    rmSync(other, { force: true });
+    if (!("ok" in answer))
+        connection.onWarning?.(`${call} answered ${answer.code}: saved as its answer; the same call in a local run throws this error, as a hosted call does now`);
+}
+export async function exportTotals(connection, out, mint, quote = null) {
+    const http = new Http(connection);
+    const key = encodeURIComponent(mint);
+    const body = await getNew(http, `/v1/functions/totals/${key}`, quote ? { quote } : {}, "totals (--totals)");
+    const info = await getNew(http, `/v1/functions/info/${key}`, {}, "totals (--totals)");
+    const content = (a) => ("ok" in a ? a.ok : a.error);
+    const totals = content(body);
+    save(connection, out, ["totals", totalsName(mint, quote)], body, totals, "tokenTotals");
+    save(connection, out, ["info", infoName(mint)], info, content(info), "tokenInfo");
+    return totals;
+}
+export async function exportVolumeSearch(connection, out, params) {
+    const http = new Http(connection);
+    mkdirSync(join(out, "volume"), { recursive: true });
+    let p = { ...params };
+    for (let pages = 1;; pages++) {
+        const flat = Object.entries(p)
+            .filter(([, v]) => v !== undefined && v !== null)
+            .map(([k, v]) => [k, String(v)]);
+        const answer = await getNew(http, "/v1/functions/volume/search", Object.fromEntries(flat), "volume searches (--volume-search)");
+        save(connection, out, ["volume", `${volumeName(flat)}.json`], answer, "ok" in answer
+            ? { params: flat, page: answer.ok }
+            : { params: flat, ...answer.error }, `volumeSearch (page ${pages})`);
+        if (!("ok" in answer))
+            return pages;
+        const page = answer.ok;
+        const next = page?.nextCursor;
+        if (next === null || next === undefined)
+            return pages;
+        if (typeof next !== "string" || next === p.cursor)
+            throw new ExportError("Invalid next cursor", "decode");
+        const w = page
+            .window;
+        if (w && typeof w === "object" && "since" in w)
+            p = { ...p, since: w.since, until: w.until };
+        p = { ...p, cursor: next };
+    }
+}

package/dist/globals.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The only globals of a hosted program besides the ECMAScript built-ins.
+ * `zyrk build` type-checks against them; in an editor, add
+ * `/// <reference types="@johannc-dev/zyrk/globals" />` with `"types": []`
+ * and `"lib": ["ES2023"]` in the program's tsconfig.
+ *
+ * Absent on purpose: `fetch` and every network API, timers, Node APIs, DOM.
+ */
+export {};
+
+declare global {
+  /** Each call becomes a `ctx.log` entry of the execution. */
+  interface Console {
+    log(...values: unknown[]): void;
+    info(...values: unknown[]): void;
+    warn(...values: unknown[]): void;
+    error(...values: unknown[]): void;
+    debug(...values: unknown[]): void;
+  }
+  var console: Console;
+
+  interface TextEncoderEncodeIntoResult {
+    read: number;
+    written: number;
+  }
+  interface TextEncoder {
+    readonly encoding: "utf-8";
+    encode(input?: string): Uint8Array;
+    encodeInto(
+      input: string,
+      destination: Uint8Array,
+    ): TextEncoderEncodeIntoResult;
+  }
+  var TextEncoder: { prototype: TextEncoder; new (): TextEncoder };
+
+  interface TextDecoder {
+    readonly encoding: string;
+    readonly fatal: boolean;
+    readonly ignoreBOM: boolean;
+    decode(
+      input?: ArrayBufferView | ArrayBuffer,
+      options?: { stream?: boolean },
+    ): string;
+  }
+  var TextDecoder: {
+    prototype: TextDecoder;
+    new (
+      label?: string,
+      options?: { fatal?: boolean; ignoreBOM?: boolean },
+    ): TextDecoder;
+  };
+
+  function structuredClone<T>(value: T): T;
+
+  interface Crypto {
+    getRandomValues<T extends ArrayBufferView | null>(array: T): T;
+  }
+  var crypto: Crypto;
+}

package/dist/hourfile.d.ts

@@ -0,0 +1,59 @@
+import { type HourBatch } from "./sdk.js";
+export declare const HOUR_MAGIC = "ZHB1";
+export type ColumnType = "u8" | "u16" | "u32" | "i32" | "u64" | "f64";
+export interface HourHeader {
+    readonly hour: number;
+    readonly source: "sealed" | "live";
+    readonly complete: boolean;
+    readonly skipped: number;
+    readonly length: number;
+    readonly addresses: readonly string[];
+    readonly signatures?: readonly (string | null)[];
+    /** Exports: timestamp of each operation counted in `skipped` (`null`: unknown). */
+    readonly skippedTimes?: readonly (number | null)[];
+    readonly market: boolean;
+    /** Market flags with one bit per virtual side; absent from older files. */
+    readonly virtualSides?: boolean;
+    readonly order: boolean;
+    /** Absent from files written before transaction ids. */
+    readonly tx?: boolean;
+    readonly columns: readonly (readonly [string, ColumnType, number])[];
+}
+/** Typed array constructors of the realm the batch is built for (a `vm` context, or Node's own). */
+export interface Realm {
+    readonly Uint8Array: Uint8ArrayConstructor;
+    readonly Uint16Array: Uint16ArrayConstructor;
+    readonly Uint32Array: Uint32ArrayConstructor;
+    readonly Int32Array: Int32ArrayConstructor;
+    readonly BigUint64Array: BigUint64ArrayConstructor;
+    readonly Float64Array: Float64ArrayConstructor;
+    readonly Array: ArrayConstructor;
+    readonly Object: ObjectConstructor;
+}
+export declare const nodeRealm: Realm;
+/** Column names and types, in the order of the sandbox's batch object. */
+export declare const COLUMNS: readonly (readonly [string, ColumnType])[];
+export declare const MARKET_COLUMNS: readonly (readonly [string, ColumnType])[];
+export declare const ORDER_COLUMNS: readonly (readonly [string, ColumnType])[];
+export declare const TX_COLUMNS: readonly (readonly [string, ColumnType])[];
+export declare class HourFileError extends Error {
+    readonly name = "HourFileError";
+}
+/** A decoded `ZHB1` buffer: its header and the raw bytes behind its columns. */
+export interface RawHour {
+    readonly header: HourHeader;
+    readonly bytes: Uint8Array;
+}
+export declare function decompressHour(file: Uint8Array): RawHour;
+/** Checks the header and every column, then the address indexes (see {@link checkIndexes}). */
+export declare function parseHour(bytes: Uint8Array): RawHour;
+/**
+ * The batch of a raw hour, every column in its own buffer (as in the
+ * sandbox), arrays of `realm`. Property order is the sandbox's.
+ */
+export declare function batchOf(raw: RawHour, realm?: Realm): HourBatch;
+/** The `ZHB1` buffer of a batch (what the server writes; used by tests and local re-cuts). */
+export declare function encodeHour(batch: HourBatch): Uint8Array;
+/** zstd with the frame checksum, as the server writes exported hours. */
+export declare function compress(raw: Uint8Array): Uint8Array;
+export declare function compressHour(batch: HourBatch): Uint8Array;