slopkit 0.2.0 → 0.4.0-rc.0

package/dist/server/config.d.ts

@@ -22,7 +22,10 @@ export type WebConfig = {
         scopes: string[];
         subjectClaim: string;
     } | undefined;
-    /** `sub:<subject>`, `email:<address>`, or `service:<client id>` for a proxy's service token. */
+    /**
+     * `sub:<subject>`, `email:<address>`, `service:<client id>` for a proxy's service token, or `key:<name>` for an
+     * agent's key (`slopkit/server/keys`).
+     */
     allow: string[];
 };
 export type Fields = Record<string, unknown>;

package/dist/server/config.js

@@ -107,10 +107,10 @@ export function parseWebConfig(value, warnings) {
     }
     const listed = web.allow ?? [];
     const allow = Array.isArray(listed)
-        ? listed.filter((entry) => typeof entry === "string" && /^(sub|email|service):.+$/.test(entry))
+        ? listed.filter((entry) => typeof entry === "string" && /^(sub|email|service|key):.+$/.test(entry))
         : [];
     if (!Array.isArray(listed) || allow.length !== listed.length) {
-        throw new Error("web.allow must list sub:<subject>, email:<address> or service:<client id>");
+        throw new Error("web.allow must list sub:<subject>, email:<address>, service:<client id> or key:<name>");
     }
     if (access === undefined && oidc === undefined) {
         throw new Error("web.json needs a login: web.access (an identity-aware proxy) or web.oidc");

package/dist/server/keys.d.ts

@@ -0,0 +1,17 @@
+/** A new key named `name`: returns its token, the only time it exists outside the agent that keeps it. */
+export declare function addKey(home: string, name: string): Promise<string>;
+/** Removes the key named `name`; whether there was one. Its token stops working at the next request. */
+export declare function revokeKey(home: string, name: string): Promise<boolean>;
+/**
+ * The keys a server checks, reread whenever the file changes (its size, time or inode), so a revocation holds from the
+ * next request. A file it can't read refuses every key until it can.
+ */
+export declare class Keys {
+    private readonly path;
+    private seen;
+    private entries;
+    constructor(home: string);
+    /** The key's name for a token, or undefined when it isn't one of ours. */
+    verify(token: string): Promise<string | undefined>;
+    private load;
+}

package/dist/server/keys.js

@@ -0,0 +1,127 @@
+/**
+ * Agent keys: bearer tokens an agent or a check sends as `Authorization: Bearer <token>`, for an app's API on its own
+ * binding without a person's login or a proxy's service token. The home keeps only each key's SHA-256
+ * (`<home>/web-keys.json`, mode 0600); the token is shown once, by `addKey`. A key's identity is `key:<name>`, allowed
+ * only when `web.allow` lists it, and it is never a person.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const FILE = "web-keys.json";
+const NAME = /^[a-z0-9-]{1,32}$/;
+const TOKEN = /^([a-z0-9-]{1,32})\.([A-Za-z0-9_-]{43})$/;
+const digest = (token) => createHash("sha256").update(token).digest();
+function parse(raw) {
+    const value = JSON.parse(raw);
+    if (!Array.isArray(value)) {
+        throw new TypeError(`${FILE} must be a list`);
+    }
+    return value.map((entry) => {
+        if (typeof entry !== "object" || entry === null) {
+            throw new TypeError(`${FILE} holds an entry that isn't an object`);
+        }
+        const { name, sha256 } = Object.fromEntries(Object.entries(entry));
+        if (typeof name !== "string" || !NAME.test(name) || typeof sha256 !== "string") {
+            throw new TypeError(`${FILE} holds an entry without a name and a sha256`);
+        }
+        return { name, sha256 };
+    });
+}
+async function read(home) {
+    const raw = await readFile(join(home, FILE), "utf-8").catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return "[]";
+        }
+        throw error;
+    });
+    return parse(raw);
+}
+async function write(home, entries) {
+    const path = join(home, FILE);
+    const temporary = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(entries, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+}
+/** Changes to one home's keys, one at a time in this process: each reads the file its predecessor wrote. */
+const writing = new Map();
+function serialized(home, change) {
+    const next = (writing.get(home) ?? Promise.resolve()).then(change, change);
+    writing.set(home, next.catch(() => undefined));
+    return next;
+}
+/** A new key named `name`: returns its token, the only time it exists outside the agent that keeps it. */
+export function addKey(home, name) {
+    if (!NAME.test(name)) {
+        return Promise.reject(new Error("a key's name is 1–32 of a-z, 0-9 and -"));
+    }
+    return serialized(home, async () => {
+        const entries = await read(home);
+        if (entries.some((entry) => entry.name === name)) {
+            throw new Error(`a key named ${name} exists; revoke it first`);
+        }
+        const token = `${name}.${randomBytes(32).toString("base64url")}`;
+        await write(home, [...entries, { name, sha256: digest(token).toString("base64url") }]);
+        return token;
+    });
+}
+/** Removes the key named `name`; whether there was one. Its token stops working at the next request. */
+export function revokeKey(home, name) {
+    return serialized(home, async () => {
+        const entries = await read(home);
+        const kept = entries.filter((entry) => entry.name !== name);
+        if (kept.length === entries.length) {
+            return false;
+        }
+        await write(home, kept);
+        return true;
+    });
+}
+/**
+ * The keys a server checks, reread whenever the file changes (its size, time or inode), so a revocation holds from the
+ * next request. A file it can't read refuses every key until it can.
+ */
+export class Keys {
+    path;
+    seen = "";
+    entries;
+    constructor(home) {
+        this.path = join(home, FILE);
+    }
+    /** The key's name for a token, or undefined when it isn't one of ours. */
+    async verify(token) {
+        const shape = TOKEN.exec(token);
+        if (shape?.[1] === undefined) {
+            return undefined;
+        }
+        const name = shape[1];
+        const entries = await this.load();
+        const entry = entries?.find((each) => each.name === name);
+        if (entry === undefined) {
+            return undefined;
+        }
+        const expected = Buffer.from(entry.sha256, "base64url");
+        const actual = digest(token);
+        return expected.length === actual.length && timingSafeEqual(expected, actual)
+            ? name
+            : undefined;
+    }
+    async load() {
+        const found = await stat(this.path).catch(() => undefined);
+        if (found === undefined) {
+            this.seen = "";
+            this.entries = [];
+            return this.entries;
+        }
+        const version = `${found.ino}:${found.size}:${found.mtimeMs}`;
+        if (version !== this.seen) {
+            try {
+                this.entries = parse(await readFile(this.path, "utf-8"));
+            }
+            catch {
+                this.entries = undefined;
+            }
+            this.seen = version;
+        }
+        return this.entries;
+    }
+}

package/dist/server/pull.js

@@ -19,6 +19,10 @@
  *   to the rows and bytes it leaves, and with no room at all the cursor stays where it was. A reset carries one row of history at least, then as many receipts as fit, then more rows; one
  *   that can't fit even so (the other tables alone are over the caps) is never sent: `pull` throws, a server fault
  *   the page sees as unavailable and retries.
+ * - **A reply costs about one encoding.** Each candidate is measured, not built: the reply as `respond` makes it with no
+ *   rows, plus each row's own encoding (every row read and encoded once) and a comma between rows; counts run once per
+ *   reply, and a candidate's coverage is read from the rows it fetched. The chosen reply is built once, and checked: one
+ *   whose bytes aren't its rows' (a `respond` that reshapes rows) is chosen again by building each candidate whole.
  * - **Receipts carry their rows.** A row a receipt names is in the reply that carries the receipt, even below the page,
  *   so a command settles only on a copy that holds its effects. A paging client names the commands it waits on (any of
  *   its pages', at most a push's worth); a receipt left out for room is asked for again by its next pull.
@@ -92,6 +96,8 @@ export function createPull(options) {
         named: db.prepare(`select * from ${paged.table} where ${key} = ?`),
     };
     const encode = (dataset, row) => JSON.stringify([dataset, paged.version, ...values(row, order)]);
+    /** Whether a row is in the order group `at`. */
+    const same = (row, at) => values(row, group).every((value, index) => value === at[index]);
     /** A cursor's order values, or undefined for one this history can't honour. */
     function decode(text, dataset) {
         let parsed;
@@ -112,27 +118,6 @@ export function createPull(options) {
             ? at.filter((value) => typeof value === "string" || typeof value === "number")
             : undefined;
     }
-    /** Where a page ending at `last` leaves the copy, at this revision. */
-    function place(dataset, from, last, more) {
-        const total = tally(sql.total.get());
-        if (last === undefined || !more) {
-            return { from, next: null, through: null, held: total, total };
-        }
-        const at = values(last, group);
-        const split = sql.split.get(...at, ...values(last, [key])) !== undefined;
-        const above = split ? sql.above.get(...at) : undefined;
-        return {
-            from,
-            next: encode(dataset, last),
-            through: split
-                ? above === undefined
-                    ? null
-                    : paged.through(Object.values(above))
-                : paged.through(at),
-            held: tally(sql.held.get(...values(last, order))),
-            total,
-        };
-    }
     function assemble(request, receipts) {
         const dataset = options.dataset();
         const revision = options.revision();
@@ -159,60 +144,166 @@ export function createPull(options) {
                 receipts: [...receipts(after)],
             });
         }
+        // Counted once per reply: every candidate page is placed from these and from the rows it was read with.
+        let total;
+        const count = () => (total ??= tally(sql.total.get()));
+        const above = new Map();
+        /** The lowest live order group above `at` (whole, so its values are the coverage boundary), once per group. */
+        const higher = (at) => {
+            const id = JSON.stringify(at);
+            if (!above.has(id)) {
+                const found = sql.above.get(...at);
+                above.set(id, found === undefined ? null : values(found, group));
+            }
+            return above.get(id) ?? null;
+        };
+        /** Each row read and encoded once, by key: a row is the same everywhere in one reply (one transaction). */
+        const encoded = new Map();
+        const row = (each) => {
+            let found = encoded.get(each[key]);
+            if (found === undefined) {
+                const value = paged.read(each);
+                found = { value, bytes: Buffer.byteLength(JSON.stringify(value)) };
+                encoded.set(each[key], found);
+            }
+            return found;
+        };
         /**
-         * A reply: `size` rows of `page` (fetched with one row more, to know if older ones are left), the first `count` of
-         * `kept` receipts with the rows they name, and `extra` history rows beside them; once each, as the store holds
-         * them now. Says whether it fits the caps, and how many rows it carries.
+         * A reply: `size` rows of `page` (fetched with one row more, to know if older ones are left, and live rows strictly
+         * below the cursor `fixed.at`, or the newest ones), the first `count` of `kept` receipts with the rows they name,
+         * and `extra` history rows beside them; once each, as the store holds them now. `held` counts the rows at or
+         * above the cursor (none on a reset). `measure` says whether one fits the caps without building it: the reply as
+         * `respond` makes it with no rows, plus each row's own encoded bytes and a comma between rows. `make` builds it.
          */
-        const reply = (fixed, page, kept, extra) => {
+        const reply = (fixed, page, kept, extra, held) => {
             const named = kept.map((each) => options.receipts.names(each).flatMap((name) => sql.named.all(name)));
-            return (size, count = kept.length) => {
-                const rows = new Map();
-                for (const row of [...page.slice(0, size), ...extra, ...named.slice(0, count).flat()]) {
-                    rows.set(row[key], rows.get(row[key]) ?? row);
+            /**
+             * Where a page of `size` rows leaves the copy: its last row (or the cursor), whether a live row of its group
+             * lies below it (the next row fetched), the group above it (in the page, else one query), and `held`.
+             */
+            const place = (size) => {
+                const last = page[size - 1] ?? fixed.at;
+                const next = page[size];
+                if (last === undefined || next === undefined) {
+                    return { from: fixed.from, next: null, through: null, held: count(), total: count() };
                 }
-                const made = answer({
-                    ...base,
-                    ...fixed,
-                    rows: [...rows.values()].map(paged.read),
-                    receipts: kept.slice(0, count),
-                    page: place(dataset, fixed.from, page[size - 1] ?? fixed.at, page.length > size),
-                });
-                const carried = rows.size + sizeOf(fixed.unpaged);
-                return { made, carried, fits: carried <= limits.maxRows && made.bytes <= limits.maxBytes };
+                const at = values(last, group);
+                let through = at;
+                // A page ending inside a group leaves it out: the boundary is the lowest whole group above.
+                if (same(next, at)) {
+                    const inPage = page.slice(0, Math.max(0, size - 1)).findLast((each) => !same(each, at));
+                    through = inPage === undefined ? higher(at) : values(inPage, group);
+                }
+                return {
+                    from: fixed.from,
+                    next: encode(dataset, last),
+                    through: through === null ? null : paged.through(through),
+                    held: held() + size,
+                    total: count(),
+                };
+            };
+            const rows = (size, taken) => {
+                const out = new Map();
+                for (const each of [...page.slice(0, size), ...extra, ...named.slice(0, taken).flat()]) {
+                    out.set(each[key], out.get(each[key]) ?? each);
+                }
+                return [...out.values()];
+            };
+            const pulled = (size, taken, carried) => ({
+                ...base,
+                ...fixed,
+                rows: carried,
+                receipts: kept.slice(0, taken),
+                page: place(size),
+            });
+            const fits = (carried, bytes) => carried + sizeOf(fixed.unpaged) <= limits.maxRows && bytes <= limits.maxBytes;
+            return {
+                /** The rows fetched for the page, one more than it may carry when older ones are left. */
+                fetched: page.length,
+                receipts: kept.length,
+                /** The reply's encoded bytes and whether it fits, from its rows' own encodings. */
+                measure: (size, taken = kept.length) => {
+                    const carried = rows(size, taken);
+                    let bytes = answer(pulled(size, taken, [])).bytes + Math.max(0, carried.length - 1);
+                    for (const each of carried) {
+                        bytes += row(each).bytes;
+                    }
+                    return { bytes, fits: fits(carried.length, bytes) };
+                },
+                /** The reply itself, and whether it fits, encoded whole. */
+                make: (size, taken = kept.length) => {
+                    const carried = rows(size, taken);
+                    const made = answer(pulled(size, taken, carried.map((each) => row(each).value)));
+                    return { made, fits: fits(carried.length, made.bytes) };
+                },
             };
         };
-        if (!reset) {
-            const unpaged = options.unpaged(since);
-            const room = cursor === null ? 0 : limits.pageRows;
-            const page = cursor === null ? [] : sql.older.all(...cursor, room + 1);
-            // The cursor as the row it stands for: a reply with no older row leaves the copy there.
-            const at = cursor === null
-                ? {}
-                : {
-                    at: Object.fromEntries(order.map((column, index) => [column, cursor[index] ?? null])),
-                };
-            const build = reply({ reset: false, from: request.page, unpaged, ...at }, page, receipts(since), sql.changes.all(since));
-            const alone = build(0);
-            // Only a delta (with its receipts' rows and the other tables) that can't fit by itself starts the copy over; the
-            // older page takes the rows and bytes it leaves.
-            if (alone.fits) {
-                const most = Math.min(room, page.length, limits.maxRows - alone.carried);
-                return build(largest(1, most, (size) => build(size).fits) ?? 0).made;
+        /** A delta's reply, and the newest page's: each read once, when first asked for. */
+        let delta;
+        let fresh;
+        const forDelta = () => {
+            if (delta === undefined) {
+                const unpaged = options.unpaged(since);
+                const room = cursor === null || cursor === undefined ? 0 : limits.pageRows;
+                const page = room === 0 ? [] : sql.older.all(...(cursor ?? []), room + 1);
+                let held;
+                // The cursor as the row it stands for: a reply with no older row leaves the copy there.
+                const at = cursor === null || cursor === undefined
+                    ? {}
+                    : {
+                        at: Object.fromEntries(order.map((column, index) => [column, cursor[index] ?? null])),
+                    };
+                delta = reply({ reset: false, from: request.page ?? null, unpaged, ...at }, page, receipts(since), sql.changes.all(since), 
+                // The live rows at or above the cursor: with the page's own rows, every row at or above its last.
+                () => (held ??= cursor ? tally(sql.held.get(...cursor)) : 0));
             }
+            return delta;
+        };
+        const forReset = () => {
+            fresh ??= reply({ reset: true, from: null, unpaged: options.unpaged(0) }, sql.top.all(limits.firstRows + 1), receipts(0), [], () => 0);
+            return fresh;
+        };
+        /**
+         * The reply's shape by `fits`: a delta that fits by itself takes the older page's rows and bytes it leaves;
+         * otherwise everything, from the newest page: one row of it at least, then as many receipts (with their rows) as
+         * fit, then as many more of the first rows. A receipt left out is asked for again by the next pull.
+         */
+        const choose = (fits) => {
+            if (!reset) {
+                const built = forDelta();
+                // Only a delta (with its receipts' rows and the other tables) that can't fit by itself starts the copy over.
+                if (fits(built, 0)) {
+                    const room = cursor === null ? 0 : limits.pageRows;
+                    const most = Math.min(room, built.fetched);
+                    return {
+                        built,
+                        size: largest(1, most, (size) => fits(built, size)) ?? 0,
+                        receipts: built.receipts,
+                    };
+                }
+            }
+            const built = forReset();
+            const least = Math.min(1, built.fetched);
+            const kept = largest(0, built.receipts, (at) => fits(built, least, at));
+            if (kept === undefined) {
+                throw new Error(`pull: the reply can't fit its caps (${limits.maxRows} rows, ${limits.maxBytes} bytes), even with one row of history`);
+            }
+            const most = Math.min(limits.firstRows, built.fetched);
+            return {
+                built,
+                size: largest(least, most, (at) => fits(built, at, kept)) ?? least,
+                receipts: kept,
+            };
+        };
+        // Measured from each row's own encoding, then built once. A reply whose encoding isn't its rows' (a `respond`
+        // that reshapes rows) is chosen again by building each candidate whole.
+        const measured = choose((built, size, taken) => built.measure(size, taken).fits);
+        const made = measured.built.make(measured.size, measured.receipts);
+        if (made.made.bytes === measured.built.measure(measured.size, measured.receipts).bytes) {
+            return made.made;
         }
-        // Everything, from the newest page: one row of it at least, then as many receipts (with their rows) as fit, then
-        // as many more of the first rows. A receipt left out is asked for again by the next pull.
-        const kept = receipts(0);
-        const page = sql.top.all(limits.firstRows + 1);
-        const least = Math.min(1, page.length);
-        const build = reply({ reset: true, from: null, unpaged: options.unpaged(0) }, page, kept, []);
-        const count = largest(0, kept.length, (at) => build(least, at).fits);
-        if (count === undefined) {
-            throw new Error(`pull: the reply can't fit its caps (${limits.maxRows} rows, ${limits.maxBytes} bytes), even with one row of history`);
-        }
-        const most = Math.min(limits.firstRows, page.length);
-        return build(largest(least, most, (at) => build(at, count).fits) ?? least, count).made;
+        const exact = choose((built, size, taken) => built.make(size, taken).fits);
+        return exact.built.make(exact.size, exact.receipts).made;
     }
     /** The reply to one request, its encoded size, and what it carries before `respond` shaped it. */
     function pull(request, caller) {

package/dist/server/store.d.ts

@@ -0,0 +1,101 @@
+import { DatabaseSync } from "node:sqlite";
+import { Jobs } from "./jobs.ts";
+import { Ledger } from "./ledger.ts";
+/**
+ * The core tables every replicated store has, before the app's own: `meta`, the command ledger's `commands`
+ * (`slopkit/server/ledger`), `jobs` (`slopkit/server/jobs`) and the `revisions` log. Never edited once shipped.
+ */
+export declare const CORE_TABLES = "create table meta(key text primary key, value text not null);\n   create table commands(\n     principal text not null check (length(principal) > 0),\n     client text not null, id integer not null check (id > 0),\n     name text not null, args text not null,\n     state text not null check (state in ('accepted', 'done', 'retired')),\n     outcome text check ((state = 'done') = (outcome is not null)),\n     revision integer check ((state = 'accepted') = (revision is null)),\n     created_at text not null,\n     primary key (principal, client, id)) strict;\n   create index commands_revision on commands(principal, client, revision);\n   create trigger commands_never_deleted before delete on commands\n     begin select raise(abort, 'a command key is kept forever: retire it'); end;\n   create table jobs(\n     id integer primary key,\n     kind text not null check (length(kind) > 0),\n     key text not null,\n     state text not null check (state in ('due', 'running', 'done', 'failed')),\n     due_at text not null, deadline_at text not null,\n     attempts integer not null default 0 check (attempts >= 0),\n     note text,\n     result text check ((state = 'done') = (result is not null)),\n     who text check ((state = 'failed') = (who is not null) and (who is null or who in ('you', 'us', 'gone'))),\n     reason text check ((state = 'failed') = (reason is not null)),\n     asked_by text not null default '[]',\n     created_at text not null, updated_at text not null);\n   create unique index jobs_open on jobs(kind, key) where state in ('due', 'running');\n   create table revisions(revision integer primary key, at text not null) strict;\n   insert into meta(key, value) values ('revision', '1'), ('history_floor', '1'),\n     ('dataset', lower(hex(randomblob(12))));";
+/** An app's store schema: its own tables at `baseVersion`, and the migrations since, one version each. */
+export type StoreSchema = {
+    /** The app's tables as a new store starts them (the core tables come first, made by the kit). */
+    base: string;
+    /** Tables a replica holds: stamped and never deleted, by trigger. */
+    replicated: readonly string[];
+    baseVersion: number;
+    /** Each moves the schema one version up from `baseVersion`; never edit a shipped one, append. */
+    migrations: readonly string[];
+    /** Indexes that only speed reads, made at every open: no row's meaning depends on one. */
+    indexes?: string;
+};
+/** The store schema a release writes: what `version --json` reports and a rollback compares. */
+export declare function schemaVersion(schema: StoreSchema): number;
+export type StoreOptions = {
+    /** The app's name, as a refusal says it ("update <name>"). */
+    name: string;
+    schema: StoreSchema;
+    now?: () => number;
+};
+export declare class SyncStore {
+    readonly db: DatabaseSync;
+    readonly path: string;
+    readonly now: () => number;
+    /**
+     * Set when the store opened older than what it had already served (restored from a backup), or a caller proved it
+     * went back: the dataset and revision it had served, and its revision then. It took a new dataset, so every replica
+     * starts over and no intent made against the lost history runs here.
+     */
+    restored: {
+        dataset: string;
+        served: number;
+        revision: number;
+    } | undefined;
+    private readonly head;
+    private servedHead;
+    private depth;
+    constructor(path: string, options: StoreOptions);
+    private userVersion;
+    private migrate;
+    /** The head beside the store: a store that opens behind what it served went back, and takes a new dataset. */
+    private checkHead;
+    /** A caller proved this store went back: it holds `seen` of this very dataset, more than the store has. */
+    wentBack(seen: number): boolean;
+    /** Record that `revision` of this dataset left the server (a pull or push reply), before the reply does. */
+    served(revision: number): void;
+    close(): void;
+    /** All of `body` or none of it. Nested calls join the outer transaction: a failure anywhere undoes all of it. */
+    transaction<T>(body: () => T): T;
+    meta(key: string): string | undefined;
+    setMeta(key: string, value: string): void;
+    /** This store's identity: a replica of another store starts over. */
+    dataset(): string;
+    revision(): number;
+    /** The store's clock as stored: now, or `at` (milliseconds). */
+    iso(at?: number): string;
+    /**
+     * Whether `revision` is one of this history: none (0), the head, at or before the floor (the revisions before they
+     * were logged), or one this store stamped and still remembers. A page holding another came from a history this store
+     * doesn't have (a restore's lost future), or is older than the log keeps: it starts over, and its taps don't run.
+     */
+    known(revision: number): boolean;
+    /**
+     * The next revision, for rows written in the current transaction: past the last, and at least the clock in
+     * microseconds (plus a random part below a millisecond), so two histories forked from one copy never stamp the same
+     * number while the clock moves forward. Each is logged (`known`).
+     */
+    stamp(): number;
+    /** The command ledger (`slopkit/server/ledger`) on this store: its transaction and its stamp. */
+    createLedger<K>(codec: {
+        encode: (receipt: K) => string;
+        decode: (text: string) => K;
+        recover?: (command: {
+            name: string;
+            args: string;
+        }) => K;
+    }): Ledger<K>;
+    /** Jobs (`slopkit/server/jobs`) on this store. */
+    createJobs<R>(codec: {
+        encode: (result: R) => string;
+        decode: (text: string) => R;
+    }): Jobs<R>;
+    /**
+     * Retention, which never deletes a key: receipts accepted more than `receiptsMs` ago retire (their outcome dropped, never acting
+     * again), logged revisions older than `revisionsMs` are forgotten except the head (a page holding one starts over),
+     * and finished jobs beyond the newest `jobsKept` of each kind are pruned.
+     */
+    retain(options?: {
+        receiptsMs?: number;
+        revisionsMs?: number;
+        jobsKept?: number;
+    }): void;
+}