@wenathlan/saddle 1.8.18 → 2.0.2

package/dist/tiers.d.ts

@@ -0,0 +1,1002 @@
+/**
+ * tiers - the "everything is VRAM" virtual memory layer of saddle.
+ *
+ * The v17 doctrine: in the end everything is VRAM. The VM impersonates
+ * physical hardware the way browsers spoof headers, and the only physical
+ * memory allowed lives in GitHub files (artifacts/GHCR), free bucket
+ * accounts and the npm CDNs. This module implements that vision on four
+ * tiers: L1 ram (Map working set plus SharedArrayBuffer ring), L2 vram
+ * (compute-bound tier of the catalog), L3 storage ram (repositories: a
+ * real node:sqlite kvstore, the npm chunk farm, GitHub REST) and L4
+ * external buckets (hf, kaggle, terabox, r2, storj, turso). It ships a
+ * real WAL SQLite backend with LRU eviction, the npm chunk planner with
+ * jsDelivr/UNPKG/esm.run URLs, a GitHub REST client that degrades to
+ * planner mode without a token, the VDR 64-bit BigInt address space with
+ * a ring that auto-flushes at the 512 MB ceiling and demotes blocks into
+ * L3, printable kernel bridge recipes (zram/tmpfs/swap/mmap/sysctl/
+ * cgroups v2), the storage==compute thesis with a real magic byte
+ * sniffer, and the memoryengine facade. Zero dependencies, node:* only,
+ * native fetch, no localhost, no emoji.
+ *
+ * Contexts (24): tierserror; TIERS catalog; LATENCYLADDER +
+ * autoscalebysize; FREEPOOL quotas; sqlitekv (WAL/LRU); storagebackend +
+ * rambufferbackend; sqlitel3backend; zip codec (crc32/zipbuild/zipread);
+ * plannpmchunks + reassembleplan + publishplan; npmchunkregistry;
+ * githubstorage (artifacts/releases/blobs); VDR addressing + memoryblock
+ * + vrdblockheaders; pagetable + localpagetable; upstashplanner;
+ * vrdringbuffer; universalvdrengine; kernel recipes (zram/tmpfs/swap);
+ * storagerambridgeplanner (mmap); sysctldropin + cgroupsv2slice;
+ * sniffmagic + virtualfilesystem; memoryengine; creatiersengine;
+ * quotaplanner (hf/kaggle/terabox/r2/storj/forges); tiersreport.
+ *
+ * Canonical sources: readme1.md lines 367-534 (memory 7-tier model,
+ * MemoryEngine API, storage to RAM bridge, SQLite as RAM), 505-519
+ * (free pool and quotas), 898-913 (VDR design). Toolchain TS 7.0.2.
+ */
+/** Error thrown by every tiers subsystem with an optional cause chain. */
+export declare class tierserror extends Error {
+    /** Machine readable subsystem tag. */
+    readonly subsystem: string;
+    constructor(message: string, options?: {
+        cause?: Error;
+        subsystem?: string;
+    });
+}
+/** Identifiers of the four virtual memory tiers. */
+export type vramtierid = 'l1' | 'l2' | 'l3' | 'l4';
+/** Static description of one virtual memory tier. */
+export type vramtier = {
+    readonly id: vramtierid;
+    readonly label: string;
+    readonly source: string;
+    readonly capacity: string;
+    readonly latencyns: number;
+    readonly detail: string;
+};
+/**
+ * TIERS: the consolidated tier model. L1 is system RAM (~100 ns, limited,
+ * ephemeral), L2 is GPU VRAM (compute-bound), L3 is storage RAM held by
+ * repositories (practically unlimited) and L4 is the external bucket farm
+ * (unlimited, quoting the ~50 us r2 edge rung of the ladder).
+ */
+export declare const TIERS: {
+    readonly l1: {
+        readonly id: 'l1';
+        readonly label: 'RAM';
+        readonly source: 'system';
+        readonly capacity: 'limited, ephemeral';
+        readonly latencyns: 100;
+        readonly detail: 'working set Map plus SharedArrayBuffer ring; zram amplification applies';
+    };
+    readonly l2: {
+        readonly id: 'l2';
+        readonly label: 'VRAM';
+        readonly source: 'gpu';
+        readonly capacity: 'limited, compute-bound';
+        readonly latencyns: 500;
+        readonly detail: 'the tier the whole VM impersonates; served by float32 VDR blocks';
+    };
+    readonly l3: {
+        readonly id: 'l3';
+        readonly label: 'Storage RAM';
+        readonly source: 'repositories';
+        readonly capacity: 'practically unlimited';
+        readonly latencyns: 10000;
+        readonly detail: 'sqlite kvstore, npm chunk packages, github artifacts and releases';
+    };
+    readonly l4: {
+        readonly id: 'l4';
+        readonly label: 'External buckets';
+        readonly source: 'hf, kaggle, terabox, r2, storj';
+        readonly capacity: 'unlimited';
+        readonly latencyns: 50000;
+        readonly detail: 'bucket farm aggregated by rclone into one virtual pool';
+    };
+};
+/** Returns one tier descriptor, throwing for unknown identifiers. */
+export declare function selecttier(id: vramtierid): vramtier;
+/** One rung of the storage-to-RAM latency ladder. */
+export type latencylevel = {
+    readonly kind: 'ram' | 'zram' | 'tmpfs' | 'mmap' | 'sqlite' | 'r2';
+    readonly latencyns: number;
+    readonly note: string;
+};
+/**
+ * LATENCYLADDER: the honest ordering of every bridge technique, from
+ * ~100 ns DRAM through ~500 ns zram pages, ~1 us tmpfs, ~5 us mmap page
+ * faults, ~10 us WAL SQLite reads, down to the ~50 us R2 edge best case.
+ */
+export declare const LATENCYLADDER: readonly latencylevel[];
+/** Returns the latency of one ladder rung, throwing for unknown kinds. */
+export declare function latencyfor(kind: latencylevel['kind']): number;
+/** Placement strategy recommended by the auto-scale rule. */
+export type autoscalestrategy = 'memfs' | 'mmap' | 'sqlite' | 'r2';
+/** Outcome of the auto-scale by size rule. */
+export type autoscaleresult = {
+    readonly strategy: autoscalestrategy;
+    readonly tier: vramtierid;
+    readonly latencyns: number;
+    readonly rationale: string;
+};
+/**
+ * autoscalebysize applies the canonical sizing rule: below 64 MB the
+ * block lives in memfs (L1), below 1 GB it rides the mmap bridge (L1 with
+ * file backing) and anything larger goes to the SQLite kvstore (L3) or to
+ * R2 (L4) when the remote hint is set.
+ */
+export declare function autoscalebysize(bytes: number, hint?: 'local' | 'remote'): autoscaleresult;
+/** One account family of the free infrastructure pool. */
+export type freepoolentry = {
+    readonly backend: string;
+    readonly quota: string;
+    readonly gb: number | null;
+    readonly source: string;
+};
+/** Citation of the free pool table (saddle docs). */
+export declare const FREEPOOLSOURCE = "saddle docs readme1.md lines 505-519 (free infrastructure pool and quotas), lines 474-492 (storage backends)";
+/**
+ * FREEPOOL: the real quota table of the only physical memory the doctrine
+ * allows. The counted families sum to 33029.5 GB (~33 TB) before the
+ * uncountable npm CDN farm joins, hence the ">33 TB" headline.
+ */
+export declare const FREEPOOL: readonly freepoolentry[];
+/** Sums the counted families and returns the headline plus npm on top. */
+export declare function freepooltotalgb(): {
+    countedgb: number;
+    headline: string;
+};
+/** Live statistics of the kvstore database. */
+export type kvstats = {
+    readonly keys: number;
+    readonly bytes: number;
+    readonly path: string;
+    readonly journalmode: string;
+    readonly oldestaccess: number | null;
+};
+/**
+ * sqlitekv is the real L3 local backend: a node:sqlite DatabaseSync file
+ * opened in the tmpdir by default (SADDLE_TIERS_DB overrides the path)
+ * with the canonical RAM pragmas (WAL, synchronous=NORMAL,
+ * cache_size=10000, temp_store=MEMORY) and the kvstore table of the
+ * docs. Reads touch the LRU column through UPDATE ... SET accessedat =
+ * strftime ... RETURNING value, lruvacuate evicts oldest-first until the
+ * budget fits, and the class is Disposable for `using` declarations.
+ */
+export declare class sqlitekv implements Disposable {
+    #private;
+    /** Absolute path of the database file. */
+    readonly path: string;
+    constructor(path?: string);
+    /** True once Symbol.dispose has closed the handle. */
+    get closed(): boolean;
+    /** Reads one key while touching the LRU clock in the same statement. */
+    get(key: string): Buffer | null;
+    /** Upserts one key with a fresh LRU clock, keeping the original createdat. */
+    set(key: string, value: Buffer): void;
+    /** Deletes one key, returning true when a row was removed. */
+    delete(key: string): boolean;
+    /** Lists keys, optionally filtered by prefix (page table reloads). */
+    keys(prefix?: string): string[];
+    /**
+     * Evicts least recently used rows until the stored bytes fit the budget,
+     * returning the evicted count; accessedat orders, createdat breaks ties.
+     */
+    lruvacuate(tobytes: number): number;
+    /** Returns the live statistics of the database. */
+    stats(): kvstats;
+    /** Closes the database handle (Disposable for `using` declarations). */
+    [Symbol.dispose](): void;
+}
+/**
+ * storagebackend is the contract every tier implements: an ordered id,
+ * the tier it serves, its ladder latency, a planner flag marking the
+ * backends that only plan IO (no token configured) and async
+ * get/set/delete so a REST call and a WAL statement share one shape.
+ */
+export interface storagebackend {
+    readonly id: string;
+    readonly tier: vramtierid;
+    readonly label: string;
+    readonly latencyns: number;
+    readonly planner: boolean;
+    get(key: string): Promise<Buffer | null>;
+    set(key: string, buffer: Buffer): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    readonly bytes?: () => number;
+}
+/**
+ * rambufferbackend is the L1 working set: a Map of keys to Buffers with
+ * an insertion-order LRU ceiling; the oldest entry drops when the ceiling
+ * is exceeded (the L3 backends still hold the bytes, so the drop is a
+ * demotion in disguise, not a loss).
+ */
+export declare class rambufferbackend implements storagebackend {
+    #private;
+    readonly id = "ram";
+    readonly tier: 'l1';
+    readonly label = "l1 ram working set (Map)";
+    readonly latencyns = 100;
+    readonly planner = false;
+    constructor(options?: {
+        readonly maxbytes?: number;
+    });
+    /** Maximum bytes kept in the working set. */
+    get maxbytes(): number;
+    get(key: string): Promise<Buffer | null>;
+    set(key: string, buffer: Buffer): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Bytes currently held by the working set. */
+    bytes(): number;
+}
+/**
+ * sqlitel3backend adapts sqlitekv to the storagebackend contract: the L3
+ * storage ram of the ladder at ~10 us per read. It owns the kv handle it
+ * creates and closes it on dispose; a borrowed handle stays open.
+ */
+export declare class sqlitel3backend implements storagebackend, Disposable {
+    #private;
+    readonly id = "sqlite";
+    readonly tier: 'l3';
+    readonly label = "l3 storage ram (node:sqlite WAL kvstore)";
+    readonly latencyns = 10000;
+    readonly planner = false;
+    constructor(options?: {
+        readonly kv?: sqlitekv;
+        readonly path?: string;
+    });
+    /** The kv handle behind this backend. */
+    get kv(): sqlitekv;
+    get(key: string): Promise<Buffer | null>;
+    set(key: string, buffer: Buffer): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Bytes stored in the kv table. */
+    bytes(): number;
+    /** Live statistics passthrough. */
+    stats(): kvstats;
+    /** Closes the kv handle when this backend owns it. */
+    [Symbol.dispose](): void;
+}
+/** CRC-32 (IEEE 802.3, polynomial 0xedb88320) of a byte payload. */
+export declare function crc32(data: Uint8Array): number;
+/** One file inside a zip archive. */
+export type zipentry = {
+    readonly name: string;
+    readonly data: Buffer;
+};
+/**
+ * zipbuild assembles a real zip archive in memory with deflate payloads
+ * from node:zlib: local file headers (PK 03 04), one central directory
+ * entry per file (PK 01 02) and the end of central directory record (PK
+ * 05 06). GitHub artifacts are zip envelopes, so the GitHub backend
+ * ships this writer instead of shelling out.
+ */
+export declare function zipbuild(entries: readonly zipentry[]): Buffer;
+/**
+ * zipread parses an archive from any zip writer: it scans the end of
+ * central directory record, walks the central directory, re-reads each
+ * local header for the true extra field length and inflates the payload
+ * with inflateRawSync.
+ */
+export declare function zipread(archive: Buffer): zipentry[];
+/** Default chunk size: 200 MB, the saddle split benchmark. */
+export declare const NPMCHUNKBYTES: number;
+/**
+ * The honest constant of the npm farm: the payload travels as
+ * dist/chunk-NNN.bin.js inside one package per chunk because the .bin.js
+ * suffix lets binary bytes pass the npm tarball scan while jsDelivr,
+ * UNPKG and esm.run serve the file verbatim from their CDNs.
+ */
+export declare const NPMCHUNKNOTE: string;
+/** One planned chunk: one npm package carrying one .bin.js file. */
+export type npmchunkplan = {
+    readonly index: number;
+    readonly packagename: string;
+    readonly filename: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly cdnurls: readonly string[];
+};
+/** The full layout planned for one payload. */
+export type npmchunklayout = {
+    readonly scope: string;
+    readonly version: string;
+    readonly chunkbytes: number;
+    readonly totalbytes: number;
+    readonly chunks: readonly npmchunkplan[];
+    readonly note: string;
+};
+/** Options of the chunk planner. */
+export type npmchunkoptions = {
+    readonly scope?: string;
+    readonly chunkbytes?: number;
+    readonly version?: string;
+};
+/**
+ * plannpmchunks splits one payload into the @scope/assets-NNN package
+ * series at 200 MB by default: each chunk gets its dist/chunk-NNN.bin.js
+ * filename, its real sha256 checksum and the three CDN URLs (jsDelivr,
+ * UNPKG, esm.run) that serve it without any npm install. A 300 MB buffer
+ * yields two chunks (200 MB + 100 MB), the canonical split of the docs.
+ */
+export declare function plannpmchunks(buffer: Buffer | Uint8Array, options?: npmchunkoptions): npmchunklayout;
+/** Reassembly plan: fetch every chunk, verify every sha256, concatenate. */
+export type reassemblyplan = {
+    readonly steps: readonly string[];
+    readonly verify: readonly string[];
+    readonly manifest: readonly {
+        readonly url: string;
+        readonly sha256: string;
+    }[];
+    readonly expectedbytes: number;
+};
+/**
+ * reassembleplan turns a layout into the executable reconstruction
+ * script: one curl per CDN URL, one sha256 verification per chunk and the
+ * final cat that rebuilds the original bytes in order.
+ */
+export declare function reassembleplan(layout: npmchunklayout): reassemblyplan;
+/** Publish plan: real npm CLI commands per chunk package. */
+export type publishplan = {
+    readonly perchunk: readonly {
+        readonly packagename: string;
+        readonly commands: readonly string[];
+    }[];
+    readonly unpublish: readonly string[];
+    readonly note: string;
+};
+/**
+ * publishplan emits the real publish sequence per chunk: package.json,
+ * payload copy into dist/, `npm publish --access public`, and optionally
+ * `npm unpublish` after the flush to a durable tier, exactly like the
+ * VDR npm-ephemeral fabric describes.
+ */
+export declare function publishplan(layout: npmchunklayout, options?: {
+    readonly unpublishafterflush?: boolean;
+}): publishplan;
+/**
+ * npmchunkregistry registers payloads as npm chunk layouts: set() plans
+ * the @scope/assets-NNN series without touching the network and get() is
+ * honest about needing the CDN fetch described by reassembleplan (this
+ * backend is a planner, flagged as such), so the engine keeps walking
+ * down the ladder instead of faking a hit.
+ */
+export declare class npmchunkregistry implements storagebackend {
+    #private;
+    readonly id = "npmchunks";
+    readonly tier: 'l3';
+    readonly label = "l3 npm cdn farm (planner: @scope/assets-NNN .bin.js chunks)";
+    readonly latencyns = 50000;
+    readonly planner = true;
+    constructor(options?: {
+        readonly scope?: string;
+        readonly chunkbytes?: number;
+    });
+    get(key: string): Promise<Buffer | null>;
+    set(key: string, buffer: Buffer): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Bytes counted across registered layouts. */
+    bytes(): number;
+    /** Returns the planned layout of one key, or null when absent. */
+    layout(key: string): npmchunklayout | null;
+    /** Lists every registered key with its chunk count. */
+    keys(): readonly {
+        readonly key: string;
+        readonly chunks: number;
+    }[];
+}
+/** Planner-mode answer: the exact call that a token would unlock. */
+export type plannedcall = {
+    readonly planned: true;
+    readonly reason: string;
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly bytes: number;
+};
+/** Outcome of an artifact or release upload. */
+export type uploadresult = plannedcall | {
+    readonly planned: false;
+    readonly status: number;
+    readonly location: string | null;
+};
+/** Options of the GitHub backend. */
+export type githuboptions = {
+    readonly owner: string;
+    readonly repo: string;
+    readonly token?: string;
+};
+/** A downloaded contents blob with its ETag and SHA (for If-Match logic). */
+export type githubblob = {
+    readonly content: Buffer;
+    readonly sha: string;
+    readonly etag: string | null;
+};
+/**
+ * githubstorage is the REST client for the only physical memory the
+ * doctrine allows: GitHub artifacts (zip envelopes from the local codec,
+ * POSTed with a correct multipart boundary), release assets on
+ * uploads.github.com (2 GiB per file, enforced locally before the wire)
+ * and the contents API as the page-table sync (GET to read, PUT with the
+ * sha of the previous revision: the honest If-Match equivalent). Without
+ * SADDLE_GITHUB_TOKEN every call degrades to planner mode and returns the
+ * exact request it would have sent. The public REST surface documents
+ * list/get/delete plus the zip download redirect; the upload path
+ * POSTs to /actions/artifacts/{id} as the Actions runtime does.
+ */
+export declare class githubstorage implements storagebackend {
+    #private;
+    readonly id = "github";
+    readonly tier: 'l3';
+    readonly label = "l3 github artifacts/releases/blobs";
+    readonly latencyns = 50000;
+    readonly owner: string;
+    readonly repo: string;
+    constructor(options: githuboptions);
+    /** True when no token is configured and every call plans instead of IO. */
+    get planner(): boolean;
+    /**
+     * uploadartifact packs the buffer into a zip envelope (one entry per
+     * artifact name) and POSTs it to the actions artifacts surface with a
+     * correct multipart/form-data boundary; planner mode returns the exact
+     * call plus the recorded target.
+     */
+    uploadartifact(name: string, buffer: Buffer, artifactid?: number): Promise<uploadresult>;
+    /**
+     * downloadartifact follows the documented zip redirect (303 to the
+     * signed URL) and unpacks the archive with the local zip codec.
+     */
+    downloadartifact(artifactid: number): Promise<zipentry[] | plannedcall>;
+    /**
+     * uploadreleaseasset streams one buffer to uploads.github.com; the
+     * 2 GiB per-file limit is enforced locally before the wire.
+     */
+    uploadreleaseasset(releaseid: number, name: string, buffer: Buffer): Promise<uploadresult>;
+    /**
+     * getblob reads one repository file through the contents API and hands
+     * back the decoded bytes plus the sha and ETag a subsequent PUT needs.
+     */
+    getblob(path: string): Promise<githubblob | null>;
+    /**
+     * putblob writes one repository file: the sha of the current revision
+     * travels in the body and the ETag (when known) rides as the If-Match
+     * header, the honest optimistic-concurrency sync behind the VDR page
+     * table on GitHub.
+     */
+    putblob(path: string, content: Buffer, options?: {
+        readonly sha?: string;
+        readonly message?: string;
+        readonly etag?: string;
+    }): Promise<uploadresult>;
+    /** Lists the calls planned so far in planner mode. */
+    planneduploads(): readonly {
+        readonly key: string;
+        readonly bytes: number;
+        readonly url: string;
+    }[];
+    /** storagebackend surface: reads blobs under tiers/ (live mode only). */
+    get(key: string): Promise<Buffer | null>;
+    /** storagebackend surface: writes blobs with sha conflict handling. */
+    set(key: string, buffer: Buffer): Promise<void>;
+    /** storagebackend surface: deletes blobs through the contents API. */
+    delete(key: string): Promise<boolean>;
+}
+/** Highest address of the VDR space: 2^64-1. */
+export declare const MAXVDRADDRESS = 18446744073709551615n;
+/** The address space in the signed reading of the VDR notes (~9.22 EB). */
+export declare const VDRADDRESSEB = 9.22;
+/** Content type of a VDR memory block on the wire. */
+export declare const VDRBLOCKCONTENTTYPE = "application/vnd.vdr-block+bin";
+/** Compression algorithms named by the X-VDR-Compression header. */
+export type vdrcompression = 'none' | 'gzip' | 'zstd';
+/** formatvdraddress renders 0x-prefixed zero padded hex, the canonical spelling. */
+export declare function formatvdraddress(address: bigint): string;
+/** parsevdraddress accepts 0x hex or decimal text and validates the range. */
+export declare function parsevdraddress(text: string): bigint;
+/** validatevdraddress asserts a non-negative 64-bit BigInt. */
+export declare function validatevdraddress(address: bigint): void;
+/**
+ * memoryblock is the Prisma-shaped record of the VDR design: a 64-bit
+ * address, its length, the optional remote home, the sha256 checksum and
+ * the compression flag. Ten GB of RAM and six hundred GB of storage are
+ * the same blocks, only the address space differs.
+ */
+export type memoryblock = {
+    readonly address: bigint;
+    readonly bytelength: number;
+    readonly remoteurl?: string;
+    readonly checksum: string;
+    readonly iscompressed: boolean;
+};
+/** Options for the real wire headers of a block. */
+export type vdrheadervalues = {
+    readonly chunkid: string;
+    readonly pointeroffset: number | bigint;
+    readonly compression: vdrcompression;
+    readonly buffer?: Uint8Array;
+    readonly checksum?: string;
+};
+/**
+ * vrdblockheaders generates the real header set of the VDR protocol:
+ * Content-Type application/vnd.vdr-block+bin plus X-VDR-Chunk-ID,
+ * X-VDR-Pointer-Offset, X-VDR-Compression and X-VDR-Integrity (sha256 of
+ * the payload bytes, computed here when a buffer is given or quoted from
+ * the stored checksum otherwise). The zstd value is accepted on the wire
+ * while this runtime compresses with gzip from node:zlib.
+ */
+export declare function vrdblockheaders(values: vdrheadervalues): Record<string, string>;
+/** The page table contract of the VDR design. */
+export interface pagetable {
+    readonly backend: string;
+    getblock(address: bigint): memoryblock | null;
+    setblock(block: memoryblock): void;
+    deleteblock(address: bigint): boolean;
+    blocks(): readonly memoryblock[];
+    size(): number;
+}
+/**
+ * localpagetable keeps blocks in a Map and (when a kv handle is given)
+ * persists every record into sqlitekv under the vdr:page: prefix, so the
+ * address space survives restarts exactly like the Upstash page table of
+ * the design, minus the network.
+ */
+export declare class localpagetable implements pagetable {
+    #private;
+    readonly backend = "local map + sqlitekv persistence";
+    constructor(options?: {
+        readonly kv?: sqlitekv;
+    });
+    getblock(address: bigint): memoryblock | null;
+    setblock(block: memoryblock): void;
+    deleteblock(address: bigint): boolean;
+    blocks(): readonly memoryblock[];
+    size(): number;
+}
+/** Plan object for the Upstash Redis REST page table. */
+export type upstashplan = {
+    readonly resturl: string;
+    readonly commands: readonly string[];
+    readonly envvars: readonly string[];
+    readonly quota: string;
+    readonly source: string;
+};
+/**
+ * upstashplanner documents the remote page table of the VDR design as a
+ * plan object: the free Upstash Redis REST tier (10k requests/day) with
+ * the real GET/SET/DEL commands for the vdr:page: keyspace. No IO is
+ * performed; the caller executes the plan when an account exists.
+ */
+export declare function upstashplanner(options?: {
+    readonly keyname?: string;
+}): upstashplan;
+/** Flush callback invoked per demoted block when the ceiling is hit. */
+export type ringflush = (address: bigint, bytes: Uint8Array) => void;
+/** Live statistics of the ring. */
+export type ringstats = {
+    readonly capbytes: number;
+    readonly usedbytes: number;
+    readonly liveblocks: number;
+    readonly flushcount: number;
+    readonly demotedbytes: number;
+};
+/** Options of the ring buffer. */
+export type ringoptions = {
+    readonly capbytes?: number;
+    readonly capmb?: number;
+    readonly onflush?: ringflush;
+};
+/**
+ * vrdringbuffer is the L1 VDRAM: one SharedArrayBuffer with a Float32Array
+ * view, 4-byte aligned slots and the auto-flush ceiling of the design
+ * (512 MB default, SADDLE_VDR_CAP in MB overrides). When a write no longer
+ * fits, every live block is flushed through the onflush callback (the
+ * transparent demotion to L3) and the cursor restarts at zero: ring
+ * paging at the RAM ceiling, exactly like the VDR notes describe.
+ */
+export declare class vrdringbuffer {
+    #private;
+    constructor(options?: ringoptions);
+    /** Ceiling in bytes. */
+    get capbytes(): number;
+    /** Bytes currently live in the ring. */
+    get usedbytes(): number;
+    /** Number of full flushes executed at the ceiling. */
+    get flushcount(): number;
+    /** Bytes handed to the demotion callback so far. */
+    get demotedbytes(): number;
+    /**
+     * writefloats stores one Float32Array payload at a 4-byte aligned slot
+     * and reports whether the ceiling forced a full flush first. Payloads
+     * larger than the whole ring are rejected (the engine demotes those
+     * straight to L3 without paging them).
+     */
+    writefloats(address: bigint, samples: Float32Array): {
+        readonly flushed: boolean;
+    };
+    /** writebytes stores an opaque byte payload (any alignment). */
+    writebytes(address: bigint, payload: Uint8Array): {
+        readonly flushed: boolean;
+    };
+    /** readfloats returns a private copy of one live float payload. */
+    readfloats(address: bigint): Float32Array | null;
+    /** readbytes returns a private copy of one live byte payload. */
+    readbytes(address: bigint): Uint8Array | null;
+    /** drop removes one address from the ring without demoting it. */
+    drop(address: bigint): boolean;
+    /** Addresses currently live, oldest first. */
+    addresses(): readonly bigint[];
+    /** flush demotes every live block now and resets the cursor. */
+    flush(): number;
+    /** Live statistics of the ring. */
+    stats(): ringstats;
+}
+/** Options of the universal VDR engine. */
+export type vdrengineoptions = {
+    readonly capmb?: number;
+    readonly pages?: pagetable;
+    readonly l3?: storagebackend | null;
+};
+/** Live statistics of the VDR engine. */
+export type vdrstats = {
+    readonly capbytes: number;
+    readonly usedbytes: number;
+    readonly liveblocks: number;
+    readonly pagetablesize: number;
+    readonly pendingdemes: number;
+    readonly demotedblocks: number;
+    readonly demotedbytes: number;
+};
+/**
+ * universalvdrengine is the L1-to-L3 pipeline of the VDR design:
+ * writevdr lands Float32Array blocks in the SharedArrayBuffer ring (L1,
+ * microsecond latency) and registers them in the page table; when the
+ * ring hits its ceiling the flush callback queues every live block for
+ * demotion into the L3 backend (gzip when the block is compressed).
+ * readvdr answers from the ring first and, on a miss, drains the pending
+ * demotions, fetches the block from L3, verifies the sha256 checksum of
+ * the design and hands back the floats: the demotion is transparent to
+ * the caller, which is the entire "everything is VRAM" thesis.
+ */
+export declare class universalvdrengine implements Disposable {
+    #private;
+    constructor(options?: vdrengineoptions);
+    /** Writes one float block at a VDR address and returns its record. */
+    writevdr(address: bigint, samples: Float32Array, options?: {
+        readonly compress?: boolean;
+    }): memoryblock;
+    /**
+     * Reads one address back as floats: the ring answers first; on a miss
+     * the pending demotions drain into L3, the block returns from storage,
+     * the checksum is verified and the floats are rebuilt. Returns null
+     * when the address never existed.
+     */
+    readvdr(address: bigint): Promise<Float32Array | null>;
+    /**
+     * freeramaddress releases one address from every tier: the ring slot,
+     * the page table record and the L3 block. Returns true when anything
+     * was actually freed.
+     */
+    freeramaddress(address: bigint): Promise<boolean>;
+    /**
+     * blockheaders renders the real wire headers of one address: integrity
+     * comes from the live bytes when the block sits in the ring and from
+     * the stored checksum after demotion.
+     */
+    blockheaders(address: bigint): Record<string, string>;
+    /** Page table accessor. */
+    get pages(): pagetable;
+    /** Ring statistics plus demotion counters. */
+    stats(): vdrstats;
+    /** Drops the ring without touching L3 (dispose path). */
+    [Symbol.dispose](): void;
+}
+/** One printable kernel recipe. */
+export type kernelrecipe = {
+    readonly kind: 'zram' | 'tmpfs' | 'swapfile';
+    readonly commands: readonly string[];
+    readonly effect: string;
+    readonly source: string;
+};
+/** Recipe sources of the bridge section. */
+export declare const RECIPESOURCE = "saddle docs readme1.md lines 398-421 (storage to RAM bridge mechanics)";
+/**
+ * zramrecipe plans the compressed RAM swap sequence: modprobe, zstd (or
+ * lz4) algorithm, disksize, mkswap, swapon with priority 100. Printable
+ * strings only: this module never executes syscalls.
+ */
+export declare function zramrecipe(sizegb?: number, algo?: 'zstd' | 'lz4'): kernelrecipe;
+/** tmpfsrecipe plans a ramdisk mount sized in gigabytes. */
+export declare function tmpfsrecipe(mount?: string, sizegb?: number): kernelrecipe;
+/** swapfilerecipe plans the fallocate/mkswap/swapon swap file sequence. */
+export declare function swapfilerecipe(path?: string, sizegb?: number): kernelrecipe;
+/** The mmap constants of the StorageRAMBridge API. */
+export declare const MMAPCONSTANTS: {
+    readonly PROT_READ: 1;
+    readonly PROT_WRITE: 2;
+    readonly MAP_SHARED: 1;
+    readonly MADV_RANDOM: 1;
+};
+/** One step of the mmap bridge plan: an argv-style operation object. */
+export type bridgeplanstep = {
+    readonly operation: string;
+    readonly args: readonly string[];
+    readonly effect: string;
+};
+/** The full mmap bridge plan. */
+export type storagerambridgeplan = {
+    readonly storagepath: string;
+    readonly ramlimitmb: number;
+    readonly syncintervalms: number;
+    readonly usesharedmemory: boolean;
+    readonly constants: typeof MMAPCONSTANTS;
+    readonly seedbytes: number;
+    readonly steps: readonly bridgeplanstep[];
+    readonly source: string;
+};
+/**
+ * storagerambridgeplanner renders the StorageRAMBridge as plan objects:
+ * seed 1 MB with fs.writeFileSync(storagePath, Buffer.alloc(1024*1024)),
+ * map with PROT_READ|PROT_WRITE and MAP_SHARED, advise MADV_RANDOM, then
+ * read/write by offset, sync with msync, grow with fs.ftruncateSync(fd,
+ * newSize) followed by a re-map, and close. Every step is an argv-style
+ * record: the module plans, the runner executes.
+ */
+export declare function storagerambridgeplanner(storagepath: string, options?: {
+    readonly ramlimitmb?: number;
+    readonly syncintervalms?: number;
+    readonly usesharedmemory?: boolean;
+}): storagerambridgeplan;
+/**
+ * sysctldropin renders the full text of /etc/sysctl.d/99-zai-memory.conf:
+ * swappiness 180 (zram-first), zeroed watermark boost, watermark scale
+ * 125, page-cluster 0 for swap randomness and overcommit_memory 1 so the
+ * address space may exceed the box.
+ */
+export declare function sysctldropin(): string;
+/** Resource bounds of one cgroups v2 slice. */
+export type slicelimits = {
+    readonly rammb?: number;
+    readonly cpupercent?: number;
+    readonly pids?: number;
+    readonly iorbps?: number;
+};
+/** Rendered cgroups v2 slice. */
+export type cgroupslice = {
+    readonly dir: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly value: string;
+    }[];
+    readonly source: string;
+};
+/**
+ * cgroupsv2slice renders the control files of one slice: subtree_control
+ * enables memory/cpu/pids/io, memory.max bounds the RAM with memory.high
+ * at 90 percent as the throttle line, swap is off, cpu.max carries the
+ * percent as quota over the 100 ms period, pids.max caps the tasks,
+ * io.max bounds the device bandwidth and memory.oom.group keeps the
+ * blast radius inside the slice.
+ */
+export declare function cgroupsv2slice(name: string, limits?: slicelimits): cgroupslice;
+/** Magic identities recognized by the sniffer. */
+export type magicid = 'elf' | 'pe' | 'png' | 'zip' | 'unknown';
+/** The magic byte catalog: true type over file extension. */
+export declare const MAGICBYTES: {
+    readonly elf: '7f454c46';
+    readonly pe: '4d5a';
+    readonly png: '89504e47';
+    readonly zip: '504b0304';
+};
+/** Outcome of one sniff. */
+export type magicresult = {
+    readonly kind: magicid;
+    readonly signature: string;
+    readonly note: string;
+};
+/**
+ * sniffmagic reads the true type of a payload from its leading bytes:
+ * ELF 7F 45 4C 46, PE 4D 5A, PNG 89 50 4E 47 and ZIP 50 4B 03 04, the
+ * four signatures of the storage==compute table. The four-byte probes run
+ * before the two-byte PE probe so 'MZ' never masks a longer match.
+ */
+export declare function sniffmagic(buffer: Uint8Array): magicresult;
+/** VFS inode: the storage-side twin of a compute buffer. */
+export type vfsinode = {
+    readonly ino: number;
+    readonly mode: number;
+    readonly size: number;
+    readonly ops: readonly string[];
+};
+/** VFS dentry: the name that binds an inode into the tree. */
+export type vfsdentry = {
+    readonly name: string;
+    readonly parent: string | null;
+    readonly inode: vfsinode;
+    readonly usage: 'process' | 'keep';
+};
+/**
+ * virtualfilesystem proves the thesis in code: mountbuffer registers the
+ * same bytes under an inode plus dentry exactly once, and the usage flag
+ * is the only difference between storage and compute. read hands back
+ * the very same Buffer reference (zero copy): the bytes never changed,
+ * only the intent did.
+ */
+export declare class virtualfilesystem {
+    #private;
+    /** Mounts one buffer as inode+dentry with the requested usage flag. */
+    mountbuffer(path: string, buffer: Buffer, usage: 'process' | 'keep'): vfsdentry;
+    /** Reads one path: the same Buffer reference that was mounted. */
+    read(path: string): Buffer | null;
+    /** The usage flag of one path: process or keep, the only difference. */
+    usageof(path: string): 'process' | 'keep' | null;
+    /** Resolves one dentry. */
+    resolve(path: string): vfsdentry | null;
+    /** Number of mounted inodes. */
+    size(): number;
+}
+/** A compute buffer: the same bytes flagged for processing. */
+export type computebuffer = {
+    readonly buffer: Buffer;
+    readonly tier: vramtierid;
+    readonly latencyns: number;
+    readonly backend: string;
+    readonly kind: magicid;
+    readonly usage: 'process';
+};
+/** A storage buffer: the same bytes flagged for keeping. */
+export type storagebuffer = {
+    readonly buffer: Buffer;
+    readonly tier: vramtierid;
+    readonly latencyns: number;
+    readonly backend: string;
+    readonly kind: magicid;
+    readonly usage: 'keep';
+};
+/** The result shape of safeload. */
+export type safeloadresult = {
+    readonly success: true;
+    readonly data: Buffer;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/** Live engine counters. */
+export type enginecounters = {
+    readonly loads: number;
+    readonly l1hits: number;
+    readonly demotions: number;
+    readonly persists: number;
+    readonly releases: number;
+};
+/**
+ * memoryengine is the facade of the docs: an ordered backend list (the
+ * tier ladder incarnate), an L1 Map cache and the load/persist/release
+ * triple. load iterates the backends and returns the first hit through
+ * transformToCompute (a copy: the documented ~2x overhead, with the
+ * magic identity sniffed on the way out); persist writes into every
+ * configured backend; release drops the key from the in-memory Map;
+ * safeload wraps load in the {success, data, error} envelope. The VFS
+ * twin of every loaded buffer is one mountbuffer call away: the same
+ * bytes, only the usage flag differs.
+ */
+export declare class memoryengine implements Disposable {
+    #private;
+    readonly name: string;
+    constructor(options?: {
+        readonly backends?: readonly storagebackend[];
+        readonly name?: string;
+    });
+    /** Describes the wired backends in tier order. */
+    backends(): readonly {
+        readonly id: string;
+        readonly tier: vramtierid;
+        readonly planner: boolean;
+    }[];
+    /**
+     * load returns the first hit across the ladder. The L1 cache answers
+     * directly; otherwise every backend is consulted in order, the first
+     * hit is cached and returned as a compute buffer. A miss on every tier
+     * throws the documented error.
+     */
+    load(key: string): Promise<computebuffer>;
+    /** persist writes the payload into every configured backend. */
+    persist(key: string, data: Buffer): Promise<readonly string[]>;
+    /** release deletes the key from the in-memory Map, per the docs. */
+    release(key: string): boolean;
+    /** safeload wraps load in the {success, data, error} envelope. */
+    safeload(key: string): Promise<safeloadresult>;
+    /**
+     * transformToCompute copies the bytes (the documented ~2x overhead),
+     * sniffs the true type from the magic prefix and flags the result for
+     * processing: the compute side of the thesis.
+     */
+    transformToCompute(buffer: Buffer, meta?: {
+        readonly tier?: vramtierid;
+        readonly latencyns?: number;
+        readonly backend?: string;
+    }): computebuffer;
+    /**
+     * transformToStorage keeps the very same Buffer reference (zero copy)
+     * and flips the usage flag to keep: the storage side of the thesis. No
+     * byte changes, which is the point.
+     */
+    transformToStorage(buffer: Buffer, meta?: {
+        readonly tier?: vramtierid;
+        readonly latencyns?: number;
+        readonly backend?: string;
+    }): storagebuffer;
+    /** Mounts one loaded key into the VFS twin under the requested usage. */
+    mount(key: string, usage: 'process' | 'keep'): vfsdentry;
+    /** Live counters of the engine. */
+    counters(): enginecounters;
+    /** Closes disposable backends (the sqlite kv among them). */
+    [Symbol.dispose](): void;
+}
+/** Configuration of the tiers engine factory. */
+export type tiersengineconfig = {
+    readonly name?: string;
+    readonly ram?: {
+        readonly maxbytes?: number;
+    } | true;
+    readonly sqlitedb?: string | true;
+    readonly npmscope?: string;
+    readonly github?: githuboptions;
+    readonly vdr?: {
+        readonly capmb?: number;
+    } | true;
+};
+/** The assembled stack returned by the factory. */
+export type tiersstack = {
+    readonly engine: memoryengine;
+    readonly kv: sqlitekv | null;
+    readonly sqlite: sqlitel3backend | null;
+    readonly npm: npmchunkregistry | null;
+    readonly github: githubstorage | null;
+    readonly vdr: universalvdrengine | null;
+    readonly modes: readonly string[];
+};
+/**
+ * creatiersengine wires the full stack from one config: the L1 ram
+ * working set, the L3 sqlite kvstore (default tmpdir, SADDLE_TIERS_DB
+ * overrides), the npm chunk planner (planner backend), the GitHub backend
+ * (planner without SADDLE_GITHUB_TOKEN, live with it) and, when vdr is
+ * requested, the universal VDR engine whose ring demotes into the same
+ * sqlite kv and whose page table persists there. The modes array states
+ * honestly which backends plan and which execute.
+ */
+export declare function creatiersengine(config?: tiersengineconfig): tiersstack;
+/** The bucket families planned by the catalog. */
+export type catalogkind = 'hf' | 'kaggle' | 'terabox' | 'r2' | 'storj' | 'gitlab' | 'forgejo' | 'gitea';
+/** One catalog plan: commands, env, quotas and citation, no faked IO. */
+export type catalogplan = {
+    readonly backend: catalogkind;
+    readonly commands: readonly string[];
+    readonly envvars: Readonly<Record<string, string>>;
+    readonly quotas: readonly string[];
+    readonly source: string;
+};
+/** Options of the catalog planner. */
+export type catalogoptions = {
+    readonly owner?: string;
+    readonly repo?: string;
+    readonly repoid?: string;
+    readonly workflowid?: string;
+    readonly uuid?: string;
+};
+/**
+ * quotaplanner renders the upload/dispatch plan of every L4 family as
+ * plan objects: the Hugging Face upload_folder dataset push with the
+ * real resolve URL pattern, the Kaggle dataset-metadata.json plus create
+ * call, the Terabox rclone serve/sync pair with --transfers 8, the
+ * R2/Storj s3 bucket writes and the GitLab/Forgejo/Gitea pipeline
+ * dispatch endpoints. Every plan carries the quota table and the saddle
+ * citation; nothing is executed here.
+ */
+export declare function quotaplanner(kind: catalogkind, options?: catalogoptions): catalogplan;
+/**
+ * tiersreport renders the printable summary of the whole layer: the four
+ * tiers with latencies, the ladder, the free pool headline with the
+ * counted families, the autoscale rule and the VDR address space. The
+ * smoke suite prints it verbatim.
+ */
+export declare function tiersreport(): string;
+//# sourceMappingURL=tiers.d.ts.map