@wenathlan/saddle 1.8.17 → 2.0.2

package/dist/virtualmemory.d.ts

@@ -0,0 +1,818 @@
+/**
+ * virtualmemory - virtual memory tiers, controllers and the host-aware
+ * extreme memory planner.
+ *
+ * This module owns everything memory related: the MEMORY_TIERS catalog with
+ * real bandwidth figures (DDR5-6400 system memory, HBM3e stacked memory at
+ * 8 TB/s, GDDR7 graphics memory at 1792 GB/s), MIG slicing profiles
+ * (1g.24gb, 2g.48gb, 4g.96gb), NUMA topology generation, huge page planning
+ * (1 GB and 2 MB), the kernel samepage merging controller, virtio ballooning,
+ * swap overcommit with vm.overcommit_memory=2 semantics, the tmpfs shader
+ * cache (20 GB), Docker memory flags (MemorySwap -1 and ShmSize 2g, the fix
+ * for the classic PyTorch DataLoader bus error), tiered memory controllers
+ * modeled on real silicon, a fluent region builder, a guarding region Proxy
+ * and the virtualmemorymanager facade that ties every technique together.
+ *
+ * The v2 merge adds two host-aware layers absorbed from the Meta sources:
+ * the placement tier taxonomy (DRAM_FAST, DRAM_SLOW, CXL_FM, CXL_PMEM,
+ * HBM_BLACKWELL, ZRAM, PMEM_DAX) with CXL 2.0/3.0 Type-3 device profiles,
+ * zram compression profiles, transparent huge page profiles and CCD-aware
+ * vCPU pinning for the Ryzen 9 9950X3D; and the memorymodularizer class
+ * that detects real host tiers (lspci CXL scan, /dev/pmem0, shared
+ * Blackwell memory), plans zram with workload-dependent compression
+ * factors, synthesizes tiered QEMU arguments, exports cgroup v2 slices and
+ * QMP runtime commands, and persists plans as JSON. /proc/meminfo
+ * generation (generateVirtualMeminfo, meminfoptions, pagealign) moved here
+ * from the processor module so every memory concern lives in one file.
+ *
+ * Modularity extremes are first class: 1 to 192 vCPUs, 1 to 1024 GB of RAM
+ * and 8 to 96 GB of VRAM, all user chosen and validated against hard limits.
+ *
+ * Bandwidth sources verified on 2026-08-22: JEDEC DDR5-6400 (51.2 GB/s per
+ * channel), NVIDIA B200 and AMD Instinct MI350X HBM3e (8 TB/s aggregate),
+ * GeForce RTX 5090 and RTX PRO 6000 Blackwell GDDR7 (1792 GB/s over a
+ * 512-bit bus). CXL figures follow the CXL 2.0/3.0 Type-3 fabric numbers
+ * (178-195 ns latency, 32-64 GB/s per x16 PCIe 5.0 link) documented in the
+ * project research; zram compression ratios (lzo-rle 3.1:1, zstd 4.2:1)
+ * follow the kernel zram documentation.
+ *
+ * Contexts (25): memoryerror, memorytierid, MEMORY_TIERS, memorylimits,
+ * MIGPROFILES, validatememoryrequest, buildnumatopology, planhugepages,
+ * ksmcontroller, ballooningcontroller, overcommitcontroller,
+ * planswapdevices, shadercachecontroller, dockerMemoryFlags,
+ * memorycontroller, memoryregion, regionledger, memorystats, memoryplan,
+ * virtualmemorymanager, placementtier, cxxldevice, zramprofile,
+ * memorymodularizer, generateVirtualMeminfo.
+ *
+ * Patterns: strategy (memorycontroller), builder (regionbuilder), registry
+ * (regionledger), proxy (guardregion), observer (memorystats), facade
+ * (virtualmemorymanager), planner (memorymodularizer).
+ * Rules: lowercase identifiers, english jsdoc, third person, no emoji,
+ * try/catch catcher on every fallible path, node:* built-ins only, and no
+ * hardcoded localhost address anywhere.
+ */
+/** Error thrown by every memory subsystem with an optional cause chain. */
+export declare class memoryerror extends Error {
+    /** Machine readable subsystem tag. */
+    readonly subsystem: string;
+    constructor(message: string, options?: {
+        cause?: Error;
+        subsystem?: string;
+    });
+}
+/** Identifiers of the supported memory tiers. */
+export type memorytierid = 'ddr5' | 'hbm3e' | 'gddr7';
+/** Static description of one memory tier. */
+export type memorytier = {
+    readonly id: memorytierid;
+    readonly label: string;
+    readonly technology: string;
+    readonly perchannelgbs: number;
+    readonly channels: number;
+    readonly modulegb: number;
+    readonly latencyns: number;
+    readonly usedfor: string;
+};
+/**
+ * MEMORY_TIERS: the catalog of virtual memory technologies with real
+ * bandwidth arithmetic. DDR5-6400 moves 51.2 GB/s per channel (2 channels
+ * on desktop parts such as Ryzen and Core Ultra, 12 channels on EPYC SP5),
+ * HBM3e delivers 8 TB/s aggregate on B200 and MI350X class accelerators and
+ * GDDR7 reaches 1792 GB/s across the 512-bit bus of RTX 5090 and RTX PRO
+ * 6000 Blackwell boards.
+ */
+export declare const MEMORY_TIERS: {
+    readonly ddr5: {
+        readonly id: 'ddr5';
+        readonly label: 'DDR5-6400 system memory';
+        readonly technology: 'DDR5 SDRAM at 6400 MT/s';
+        readonly perchannelgbs: 51.2;
+        readonly channels: 12;
+        readonly modulegb: 96;
+        readonly latencyns: 76;
+        readonly usedfor: 'guest RAM, page cache, tmpfs shader cache';
+    };
+    readonly hbm3e: {
+        readonly id: 'hbm3e';
+        readonly label: 'HBM3e stacked memory';
+        readonly technology: 'high bandwidth memory 3e, 8 stacks';
+        readonly perchannelgbs: 1000;
+        readonly channels: 8;
+        readonly modulegb: 36;
+        readonly latencyns: 29;
+        readonly usedfor: 'datacenter accelerator memory (B200 192 GB, MI350X 288 GB)';
+    };
+    readonly gddr7: {
+        readonly id: 'gddr7';
+        readonly label: 'GDDR7 graphics memory';
+        readonly technology: 'GDDR7 at 28 Gbps over a 512-bit bus';
+        readonly perchannelgbs: 224;
+        readonly channels: 8;
+        readonly modulegb: 16;
+        readonly latencyns: 42;
+        readonly usedfor: 'workstation and consumer GPUs (RTX 5090, RTX PRO 6000)';
+    };
+};
+/** Returns one tier descriptor, throwing for unknown identifiers. */
+export declare function selecttier<const T extends memorytierid>(id: T): memorytier;
+/** Aggregated bandwidth of one tier in GB/s (per channel times channels). */
+export declare function tierbandwidthgbs(id: memorytierid): number;
+/** Numeric bounds enforced for every memory request. */
+export type memorylimits = {
+    readonly minvcpu: number;
+    readonly maxvcpu: number;
+    readonly minramgb: number;
+    readonly maxramgb: number;
+    readonly minvramgb: number;
+    readonly maxvramgb: number;
+};
+/** Extremes of modularity supported by the virtual memory planner. */
+export declare const memorylimits: {
+    readonly minvcpu: 1;
+    readonly maxvcpu: 192;
+    readonly minramgb: 1;
+    readonly maxramgb: 1024;
+    readonly minvramgb: 8;
+    readonly maxvramgb: 96;
+};
+/** A memory request submitted by the user for planning and validation. */
+export type memoryrequest = {
+    readonly vcpus?: number;
+    readonly ramgb?: number;
+    readonly vramgb?: number;
+    readonly mig?: migprofileid;
+    readonly tier?: memorytierid;
+};
+/** Outcome of validating a memory request. */
+export type memoryrequestresult = {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+    readonly plan: memoryplan | null;
+};
+/** MIG slicing profile identifier, or off for a monolithic device. */
+export type migprofileid = '1g.24gb' | '2g.48gb' | '4g.96gb' | 'off';
+/** Static description of one MIG slicing profile. */
+export type migprofile = {
+    readonly id: migprofileid;
+    readonly slicegb: number;
+    readonly maxinstances: number;
+};
+/**
+ * MIG profiles available on the 96 GB virtual device. The identifiers keep
+ * the NVIDIA convention of compute-slice names: 1g.24gb exposes 24 GB
+ * slices (up to 4 instances), 2g.48gb exposes 48 GB slices (up to 2
+ * instances) and 4g.96gb dedicates the full 96 GB to one instance.
+ */
+export declare const MIGPROFILES: readonly migprofile[];
+/** Resolves a MIG profile by identifier, throwing for unknown names. */
+export declare function getmigprofile(id: migprofileid): migprofile | null;
+/**
+ * Validates a memory request against the hard limits and the MIG catalog.
+ * The function reuses the rule style of the core validator: it accumulates
+ * errors for limit violations, warnings for suspicious-but-legal layouts
+ * (for example RAM below 16 GB with 96 GB of VRAM, or ballooning suggested
+ * when RAM exceeds 512 GB) and builds a plan when the request is valid.
+ */
+export declare function validatememoryrequest(request: memoryrequest): memoryrequestresult;
+/** NUMA topology of a virtual machine. */
+export type numatopology = {
+    readonly nodes: number;
+    readonly cpuranges: readonly string[];
+    readonly distances: readonly (readonly number[])[];
+    readonly description: string;
+};
+/**
+ * Builds a NUMA topology for a vCPU count split across a node count. Local
+ * distance is 10 and remote nodes sit at 32, mirroring the NPS modes of
+ * AMD EPYC parts; cpu ranges are rendered as the compact lists used by
+ * lscpu and numactl.
+ */
+export declare function buildnumatopology(vcpus: number, nodes: number): numatopology;
+/** Curated NUMA presets for common EPYC thread counts. */
+export declare const NUMATOPOLOGIES: readonly numatopology[];
+/** One huge page reservation request. */
+export type hugepageconfig = {
+    readonly size: '1G' | '2M';
+    readonly count: number;
+    readonly coversgb: number;
+};
+/**
+ * Plans huge page reservations for a RAM size. Machines with at least 256 GB
+ * reserve half of their RAM as 1 GB pages for large model weights, plus a
+ * pool of 2048 2 MB pages for medium allocations; smaller machines keep a
+ * 2 MB-only layout.
+ */
+export declare function planhugepages(ramgb: number): hugepageconfig[];
+/**
+ * Kernel samepage merging controller. KSM scans anonymous pages and merges
+ * identical ones, which matters for dense virtual machines running the same
+ * runtime image; the controller models the sysfs knobs documented by the
+ * kernel (run, pages_to_scan, sleep_millisecs, merge_across_nodes) and
+ * estimates the deduplication ratio from the shared/sharing counters.
+ */
+export declare class ksmcontroller {
+    #private;
+    constructor(pagestoscan?: number, sleepmillisecs?: number);
+    /** Enables KSM and returns the sysfs writes required. */
+    enable(): string[];
+    /** Disables KSM, leaving the scan counters untouched. */
+    disable(): string[];
+    /** Tunes the scanner aggressiveness. */
+    tune(pagestoscan: number, sleepmillisecs: number): this;
+    /** Reports whether the controller is currently enabled. */
+    get running(): boolean;
+    /**
+     * Estimates the deduplication ratio from the classic kernel counters:
+     * pages_shared counts merged unique pages and pages_sharing counts the
+     * extra references pointing at them.
+     */
+    estimatesavings(pagesshared: number, pagessharing: number): {
+        ratio: number;
+        freedmb: number;
+    };
+    /** Renders the sysfs plan for logs and provisioners. */
+    describe(): Record<string, unknown>;
+}
+/**
+ * Virtio ballooning controller. The balloon lets the host reclaim guest
+ * memory on demand and gives it back under pressure; the controller tracks
+ * the current target and honors a deflate-on-OOM policy so guests never
+ * deadlock while the balloon is inflated.
+ */
+export declare class ballooningcontroller {
+    #private;
+    constructor(maxmb: number);
+    /** Inflates the balloon to a target in MB, clamped to the maximum. */
+    inflate(targetmb: number): number;
+    /** Deflates the balloon by the requested amount, floored at zero. */
+    deflate(amountmb: number): number;
+    /** Current balloon target in MB. */
+    get targetmb(): number;
+    /** Renders the QEMU device plan for the balloon. */
+    describe(): Record<string, unknown>;
+}
+/**
+ * Swap overcommit controller implementing the vm.overcommit_memory=2
+ * semantics documented in Documentation/mm/overcommit-accounting.rst: the
+ * total committed address space may never exceed swap plus a configurable
+ * percentage of RAM (overcommit_ratio, default 50). The controller computes
+ * the commit limit and recommends swap sizing for a target commit budget.
+ */
+export declare class overcommitcontroller {
+    #private;
+    constructor(ratio?: number);
+    /** Sets the overcommit ratio percentage applied in mode 2. */
+    setratio(ratio: number): this;
+    /** Computes the commit limit in GB for a RAM and swap configuration. */
+    commitlimitgb(ramgb: number, swapgb: number): number;
+    /** Recommends the swap size in GB for a desired commit budget. */
+    recommendswapgb(ramgb: number, targetcommitgb: number): number;
+    /** Renders the sysctl dictionary for this controller. */
+    sysctl(): Record<string, string>;
+    /** Renders the controller plan for logs and provisioners. */
+    describe(): Record<string, unknown>;
+}
+/** One swap backing store attached to the virtual machine. */
+export type swapdevice = {
+    readonly kind: 'zram' | 'swapfile' | 'partition';
+    readonly sizegb: number;
+    readonly priority: number;
+    readonly compressed: boolean;
+};
+/**
+ * Plans swap devices for a RAM size. ZRAM (compressed in-memory swap,
+ * priority 100) covers latency-sensitive reclaim while a swapfile or
+ * partition (priority -2) extends the commit budget required by mode 2
+ * overcommit for RAM-heavy builds.
+ */
+export declare function planswapdevices(ramgb: number): swapdevice[];
+/**
+ * Tmpfs shader cache controller. Mesa keeps its on-disk shader cache in
+ * MESA_SHADER_CACHE_DIR; hosting it on a size-capped tmpfs (20 GB by
+ * default) removes disk latency from shader compilation storms typical of
+ * LLVMpipe and Lavapipe sessions.
+ */
+export declare class shadercachecontroller {
+    #private;
+    constructor(sizegb?: number, mountpoint?: string);
+    /** Renders the fstab line for the tmpfs mount. */
+    fstabline(): string;
+    /** Renders the environment block pointing Mesa at the cache. */
+    environment(): Record<string, string>;
+    /** Mount size in GB. */
+    get sizegb(): number;
+    /** Renders the controller plan for logs and provisioners. */
+    describe(): Record<string, unknown>;
+}
+/** Options for the Docker memory flag generator. */
+export type dockermemoryoptions = {
+    readonly ramgb?: number;
+    readonly shmsizegb?: number;
+    readonly unlimitedswap?: boolean;
+};
+/** Result of the Docker memory flag generator. */
+export type dockermemoryflags = {
+    readonly run: readonly string[];
+    readonly compose: Readonly<Record<string, unknown>>;
+    readonly sysctl: Readonly<Record<string, string>>;
+    readonly rationale: readonly string[];
+};
+/**
+ * Generates Docker memory flags for a container. MemorySwap -1 keeps swap
+ * unlimited as documented by Docker ("unlimited swap, up to the amount
+ * available on the host system"), ShmSize 2g raises /dev/shm from the 64 MB
+ * default which is the canonical fix for the PyTorch DataLoader bus error,
+ * and the tmpfs entry mounts the 20 GB shader cache. Every value remains a
+ * suggestion: callers override before use.
+ */
+export declare function dockerMemoryFlags(options?: dockermemoryoptions): dockermemoryflags;
+/** Result of one simulated memory transfer. */
+export type transferview = {
+    readonly tier: memorytierid;
+    readonly bytes: number;
+    readonly direction: 'read' | 'write';
+    readonly effectivengbs: number;
+    readonly timemicros: number;
+};
+/** Common contract implemented by every tier controller (Strategy). */
+export interface memorycontroller {
+    readonly tier: memorytierid;
+    readonly totalgb: number;
+    readonly bandwidthgbs: number;
+    transfer(bytes: number, direction: 'read' | 'write'): transferview;
+    latencyns(): number;
+    describe(): Record<string, unknown>;
+}
+/** DDR5 controller: channels aggregated, bandwidth scales linearly. */
+export declare class ddr5controller implements memorycontroller {
+    #private;
+    readonly tier: memorytierid;
+    constructor(channels?: number, totalgb?: number);
+    /** Aggregate bandwidth in GB/s for the configured channel count. */
+    get bandwidthgbs(): number;
+    /** Total capacity in GB. */
+    get totalgb(): number;
+    /** Simulates one transfer over the DDR5 interconnect. */
+    transfer(bytes: number, direction: 'read' | 'write'): transferview;
+    /** Average column access latency in nanoseconds. */
+    latencyns(): number;
+    /** Renders the controller plan for logs and provisioners. */
+    describe(): Record<string, unknown>;
+}
+/** HBM3e controller: eight stacks, 8 TB/s aggregate, near-SRAM latency. */
+export declare class hbm3econtroller implements memorycontroller {
+    #private;
+    readonly tier: memorytierid;
+    constructor(stacks?: number, totalgb?: number);
+    /** Aggregate bandwidth in GB/s for the configured stack count. */
+    get bandwidthgbs(): number;
+    /** Total capacity in GB. */
+    get totalgb(): number;
+    /** Simulates one transfer over the HBM3e fabric. */
+    transfer(bytes: number, direction: 'read' | 'write'): transferview;
+    /** Stack access latency in nanoseconds. */
+    latencyns(): number;
+    /** Renders the controller plan for logs and provisioners. */
+    describe(): Record<string, unknown>;
+}
+/** GDDR7 controller: 512-bit bus, 1792 GB/s at full width. */
+export declare class gddr7controller implements memorycontroller {
+    #private;
+    readonly tier: memorytierid;
+    constructor(channels?: number, totalgb?: number);
+    /** Aggregate bandwidth in GB/s for the configured bus width. */
+    get bandwidthgbs(): number;
+    /** Total capacity in GB. */
+    get totalgb(): number;
+    /** Simulates one transfer over the GDDR7 bus. */
+    transfer(bytes: number, direction: 'read' | 'write'): transferview;
+    /** Memory access latency in nanoseconds. */
+    latencyns(): number;
+    /** Renders the controller plan for logs and provisioners. */
+    describe(): Record<string, unknown>;
+}
+/**
+ * Controller factory (Factory plus Registry patterns): maps a tier
+ * identifier to a controller instance sized by the caller. The const type
+ * parameter preserves literal tier identifiers through the call.
+ */
+export declare function creatememorycontroller<const T extends memorytierid>(tier: T, totalgb: number, channels?: number): memorycontroller;
+/** Purpose categories of a virtual memory region. */
+export type regionpurpose = 'guest' | 'modelweights' | 'shadercache' | 'scratch' | 'pinned';
+/** A virtual memory region bound to a tier and a purpose. */
+export declare class memoryregion {
+    #private;
+    readonly id: string;
+    readonly tier: memorytierid;
+    readonly purpose: regionpurpose;
+    readonly sizegb: number;
+    constructor(tier: memorytierid, purpose: regionpurpose, sizegb: number);
+    /** Number of tracked accesses through proxies or direct reads. */
+    get accesses(): number;
+    /** True while the region holds virtual backing. */
+    get allocated(): boolean;
+    /** Counts one access; used by the guarding Proxy. */
+    touch(): void;
+    /** Releases the region; idempotent and safe to call twice. */
+    release(): void;
+    /** Synchronous disposer so regions compose with `using` declarations. */
+    [Symbol.dispose](): void;
+    /** Renders the region plan for logs and provisioners. */
+    describe(): Record<string, unknown>;
+}
+/**
+ * Fluent builder for memory regions. The builder accumulates tier, purpose
+ * and size, validates the result against the tier capacity and produces a
+ * memoryregion registered in the regionledger.
+ */
+export declare class regionbuilder {
+    #private;
+    constructor();
+    /** Selects the memory tier backing the region. */
+    withtier(tier: memorytierid): this;
+    /** Selects the purpose tag of the region. */
+    withpurpose(purpose: regionpurpose): this;
+    /** Sets the region size in GB. */
+    withsize(sizegb: number): this;
+    /** Validates and materializes the region, registering it in the ledger. */
+    build(): memoryregion;
+}
+/**
+ * Wraps a region in a guarding Proxy (Proxy pattern). Every property access
+ * is counted and recorded in the access ledger; accesses to released
+ * regions raise a memoryerror so consumers notice stale handles
+ * immediately instead of silently reading freed virtual memory.
+ */
+export declare function guardregion(region: memoryregion): memoryregion;
+/** Ledger of every live region, keyed by region id (Map first policy). */
+export declare const regionledger: ReadonlyMap<string, memoryregion>;
+/** Records an access probe for a region without keeping it alive. */
+export declare function proberegion(region: memoryregion, accesses: number): void;
+/** Reads the last access probe recorded for a region, if any. */
+export declare function readprobe(region: memoryregion): number | null;
+/** Sums the size of every allocated region in the ledger. */
+export declare function totalallocatedgb(): number;
+/** Payload published when a watermark is crossed. */
+export type pressureevent = {
+    readonly level: 'low' | 'high' | 'critical';
+    readonly usedfraction: number;
+    readonly at: number;
+};
+/** Listener signature of the pressure observer. */
+export type pressurelistener = (event: pressureevent) => void;
+/**
+ * Memory pressure observer. The observer keeps listeners in a Map keyed by
+ * name (never bound to a runtime event loop) and evaluates samples against
+ * the classic watermarks: low at 85 percent, high at 95 percent and
+ * critical at 99 percent of the tracked capacity.
+ */
+export declare class memorystats {
+    #private;
+    constructor(capacitygb: number);
+    /** Subscribes a named listener to pressure transitions. */
+    subscribe(name: string, listener: pressurelistener): this;
+    /** Removes a named listener; returns true when it existed. */
+    unsubscribe(name: string): boolean;
+    /** Evaluates one used-memory sample and publishes level transitions. */
+    evaluate(usedgb: number): pressureevent | null;
+    /** Peak observed usage fraction since construction. */
+    get peak(): number;
+    /** Mean observed usage fraction since construction. */
+    get mean(): number;
+}
+/** Complete memory plan of one virtual machine. */
+export type memoryplan = {
+    readonly vcpus: number;
+    readonly ramgb: number;
+    readonly vramgb: number;
+    readonly tier: memorytierid;
+    readonly mig: migprofileid;
+    readonly miginstances: number;
+    readonly rambandwidthgbs: number;
+    readonly vrambandwidthgbs: number;
+    readonly hugepages: readonly hugepageconfig[];
+    readonly swapdevices: readonly swapdevice[];
+    readonly numa: numatopology;
+    readonly shmsizegb: number;
+    readonly shadercachesizegb: number;
+};
+/**
+ * Computes the full memory plan for a machine: bandwidth per tier, MIG
+ * instance count, huge page layout, swap devices, NUMA topology, /dev/shm
+ * size and the shader cache ceiling.
+ */
+export declare function planmemory(vcpus: number, ramgb: number, vramgb: number, mig: migprofileid, tier: memorytierid): memoryplan;
+/**
+ * Renders kernel boot arguments for the memory techniques enabled by a
+ * plan: default 1 GB huge pages plus a 2 MB pool, and the MIG-aware NUMA
+ * hints consumed by the virtual machine launcher.
+ */
+export declare function buildKernelArgs(plan: memoryplan): string;
+/**
+ * Facade that composes every memory technique for one machine. The manager
+ * exposes the plan, the sysctl dictionary, the kernel arguments, the Docker
+ * flags, the tier controllers and the pressure observer, and keeps all
+ * mutable state in Maps so the instance stays runtime agnostic.
+ */
+export declare class virtualmemorymanager {
+    #private;
+    constructor(plan: memoryplan);
+    /** The frozen plan this manager was constructed from. */
+    get plan(): memoryplan;
+    /** The pressure observer of this machine. */
+    get stats(): memorystats;
+    /** The KSM controller of this machine. */
+    get ksm(): ksmcontroller;
+    /** The ballooning controller of this machine. */
+    get balloon(): ballooningcontroller;
+    /** Returns the controller bound to a tier, when configured. */
+    controller(tier: memorytierid): memorycontroller | null;
+    /** Simulates a synthetic workload sample and evaluates pressure. */
+    sample(): pressureevent | null;
+    /** Renders the sysctl dictionary of every controller. */
+    sysctl(): Record<string, string>;
+    /** Renders the kernel boot arguments for this machine. */
+    kernelargs(): string;
+    /** Renders the Docker memory flags for this machine. */
+    dockerflags(): dockermemoryflags;
+    /** Renders the fstab line of the shader cache tmpfs. */
+    cachefstab(): string;
+    /** Renders a complete JSON-safe description of the machine memory. */
+    describe(): Record<string, unknown>;
+}
+/**
+ * Factory that builds a virtualmemorymanager from a raw request. The
+ * request is validated against the hard limits; failures raise memoryerror
+ * with the accumulated validation errors for quick diagnosis.
+ */
+export declare function createVirtualMemory(request: memoryrequest): virtualmemorymanager;
+/**
+ * Placement tier taxonomy for the host-aware planner. The technology and
+ * bandwidth catalog stays in memorytierid (ddr5, hbm3e, gddr7); placement
+ * labels describe WHERE bytes live relative to the NUMA and fabric
+ * topology, mirroring the Meta MemoryTierLabel without merging the two
+ * enums.
+ */
+export type placementtier = 'DRAM_FAST' | 'DRAM_SLOW' | 'CXL_FM' | 'CXL_PMEM' | 'HBM_BLACKWELL' | 'ZRAM' | 'PMEM_DAX';
+/** One placement tier instance with its QEMU memory backend. */
+export type placementspec = {
+    readonly tier: placementtier;
+    readonly sizemb: number;
+    readonly latencyns: number;
+    readonly bandwidthgbps: number;
+    readonly compressionratio?: number;
+    readonly persistent?: boolean;
+    readonly qemubackend: 'memory-backend-ram' | 'memory-backend-memfd' | 'memory-backend-file';
+    readonly extraopts?: Readonly<Record<string, string | number | boolean>>;
+};
+/**
+ * CXL 2.0/3.0 Type-3 memory expansion device. Latency spans 178-195 ns and
+ * bandwidth 32-64 GB/s per x16 PCIe 5.0 link depending on the spec
+ * revision; interleave ways of 2, 4 or 8 spread accesses across decoders.
+ */
+export type cxxldevice = {
+    readonly id: string;
+    readonly spec: '2.0' | '3.0';
+    readonly type: 'type3' | 'switch';
+    readonly sizemb: number;
+    readonly latencyns: number;
+    readonly bwgbps: number;
+    readonly qosclass: number;
+    readonly decoders: number;
+    readonly interleaveways: 2 | 4 | 8;
+};
+/** zram compression profile: lzo-rle favors fast decompression, zstd ratio. */
+export type zramprofile = {
+    readonly device: string;
+    readonly algorithm: 'lzo-rle' | 'zstd' | 'lzo' | 'lz4';
+    readonly level?: number;
+    readonly disksizemb: number;
+    readonly compratioachieved: number;
+    readonly memusedmb: number;
+    readonly mountpoint: string;
+};
+/** Huge page allocation profile including the transparent policy and memfd. */
+export type hugepageprofile = {
+    readonly size: '2M' | '1G';
+    readonly count: number;
+    readonly mount: '/dev/hugepages' | '/dev/hugepages-1G';
+    readonly transparent: 'always' | 'madvise' | 'never';
+    readonly shared: boolean;
+    readonly memfd: boolean;
+};
+/**
+ * CCD-aware vCPU pinning map for the Ryzen 9 9950X3D. CCD0 carries the 3D
+ * V-Cache stacks (96 MB L3) and is preferred for latency-sensitive work;
+ * CCD1 (32 MB L3) serves throughput work such as audio and IO threads.
+ */
+export type vcpupinningmap = {
+    readonly vmid: string;
+    readonly totalvcpus: number;
+    readonly topology: {
+        readonly sockets: number;
+        readonly dies: number;
+        readonly ccds: number;
+        readonly cores: number;
+        readonly threads: number;
+    };
+    readonly ccd0: {
+        readonly cpus: readonly number[];
+        readonly vcache: true;
+        readonly l3mb: 96;
+        readonly preferredfor: readonly string[];
+    };
+    readonly ccd1: {
+        readonly cpus: readonly number[];
+        readonly vcache: false;
+        readonly l3mb: 32;
+        readonly preferredfor: readonly string[];
+    };
+    readonly pinning: Map<number, readonly number[]>;
+    readonly isolated: readonly number[];
+    readonly numapolicy: 'strict' | 'preferred' | 'interleave';
+    readonly emulatorpin: readonly number[];
+};
+/** Host-aware plan produced by the memorymodularizer (camelCase shape). */
+export type hostmemoryplan = {
+    readonly vmid: string;
+    readonly totalrequestedmb: number;
+    readonly effectiveusablemb: number;
+    readonly tiers: readonly placementspec[];
+    readonly hugepages: hugepageprofile;
+    readonly zram: zramprofile;
+    readonly cxl: readonly cxxldevice[];
+    readonly vcpu: vcpupinningmap;
+    readonly qemuargs: readonly string[];
+    readonly backendsdigest: string;
+};
+/** Policy selector for the host-aware tier distribution. */
+export type tierpolicy = 'performance' | 'capacity' | 'balanced';
+/** zram algorithm selector shared by the planner and the profile type. */
+export type zramalgorithm = zramprofile['algorithm'];
+/**
+ * Host-aware extreme memory planner, the fusion of the Meta
+ * MemoryModularizer and ExtremeMemoryPlanner. The planner detects the real
+ * host memory tiers (CXL fabric devices via lspci, PMEM DAX devdax nodes,
+ * shared Blackwell HBM), tunes zram with workload-dependent compression
+ * factors, plans host-aware huge pages, pins vCPUs across the 9950X3D CCD
+ * layout, synthesizes the tiered QEMU arguments, exports cgroup v2 slices
+ * and QMP runtime commands, and persists the plan as JSON. All host
+ * interaction is best effort: every probe is wrapped in a catcher and
+ * degrades to the documented defaults.
+ */
+export declare class memorymodularizer {
+    #private;
+    constructor(options?: {
+        configdir?: string;
+    });
+    /** Host logical thread count observed at construction. */
+    get hostthreads(): number;
+    /**
+     * Detects the real host tiers. DRAM splits 70/30 into fast and slow
+     * bands; an lspci scan for CXL vendor 1e98 or an explicit qemu.config
+     * cxl_enabled flag adds a CXL_FM tier; /dev/pmem0 adds a persistent
+     * PMEM_DAX tier (128 GB, 300 ns, 15 GB/s); a shared_host_mem blackwell
+     * flag exposes half of the GPU VRAM as HBM_BLACKWELL through memfd.
+     */
+    detecthosttiers(): placementspec[];
+    /**
+     * Plans zram sizing and command sequence for a requested capacity. The
+     * compression factor adapts to the workload type from passage.config
+     * (media_transcode 1.8, build 3.2, default 2.5) and to the algorithm
+     * (zstd x1.15, lzo-rle x0.92); the disksize takes 30 percent of the
+     * request and the returned commands cover modprobe, comp_algorithm,
+     * disksize, mkswap and swapon at priority 100.
+     */
+    configurezram(requestedmb: number, algorithm?: zramalgorithm, workload?: string): {
+        enabled: boolean;
+        factor: number;
+        disksizemb: number;
+        commands: readonly string[];
+    };
+    /**
+     * Host-aware huge page planning. Unlike the static planhugepages this
+     * variant reads HugePages_Total from /proc/meminfo, honors the thp_enabled
+     * knob from qemu.config for the transparent policy and mounts under
+     * /dev/hugepages or /dev/hugepages-1G depending on the preferred size.
+     */
+    planhugepageshost(totalmb: number, prefer?: '2M' | '1G'): {
+        sizekb: number;
+        count: number;
+        mount: string;
+        transparent: boolean;
+    };
+    /**
+     * Builds the CCD-aware pinning map for a virtual machine. Even vCPUs map
+     * onto CCD0 (the 3D V-Cache complex) and odd vCPUs onto CCD1; two host
+     * threads stay isolated for the emulator and the host. X3D parts report
+     * two dies, matching the 9950X3D topology.
+     */
+    buildpinningmap(vmid: string, vcpucount: number): {
+        vmid: string;
+        map: Map<number, readonly number[]>;
+        isolated: readonly number[];
+        topology: {
+            sockets: number;
+            dies: number;
+            cores: number;
+            threads: number;
+        };
+    };
+    /**
+     * Builds the complete host-aware plan for a virtual machine. The memory
+     * tier policy (performance, capacity or balanced) selects the tier mix:
+     * performance dedicates DRAM_FAST, capacity spreads 60/30/10 across
+     * DRAM/CXL/zram and balanced keeps 70/20 DRAM/zram plus 10 percent
+     * Blackwell HBM when the shared flag is set. The plan carries the tiered
+     * QEMU argument synthesis (cxl-type3 on bus cxl.0, virtio-mem-pci with 2M
+     * blocks for HBM, memory-backend-ram/memfd/file objects, two NUMA nodes,
+     * the avx-512 host cpu line, the balloon with free-page reporting and the
+     * vsock chardev) and the compression-adjusted effective usable capacity.
+     */
+    buildhostplan(vmid: string, options?: {
+        requestedmb?: number;
+        vcpus?: number;
+        policy?: tierpolicy;
+    }): hostmemoryplan;
+    /**
+     * Calculates the balloon target under host pressure. Pressure below 0.3
+     * leaves the guest untouched; above it the balloon reclaims half of the
+     * excess, never dropping below 50 percent of the current allocation. A
+     * host free memory below 4 GB escalates the effective pressure to at
+     * least 0.5 so the balloon engages before the host starts swapping.
+     */
+    calculateballoontarget(currentmb: number, hostfreemb: number, pressure: number): number;
+    /**
+     * Renders the cgroup v2 slice configuration for a plan: MemoryMax at the
+     * requested size, MemorySwapMax at 1.5x, AllowedCPUs from the isolated
+     * pinning set and MemoryZSwapMax at the zram disksize.
+     */
+    generatecgroupv2config(plan: hostmemoryplan): string;
+    /**
+     * Exports the QMP runtime commands that apply a plan without a restart:
+     * one balloon command sized to the requested memory plus object-add
+     * commands for every CXL fabric tier.
+     */
+    exportqmpmemorycommands(plan: hostmemoryplan): ReadonlyArray<Record<string, unknown>>;
+    /**
+     * Persists a plan as JSON next to the caller's chosen path. The pinning
+     * Map is materialized as a plain object so the file round-trips without
+     * loss; write failures raise a memoryerror with the cause chain.
+     */
+    saveplan(plan: hostmemoryplan, outpath?: string): string;
+}
+/** Optional overrides accepted by generateVirtualMeminfo. */
+export type meminfoptions = {
+    readonly swapgb?: number;
+    readonly vcpus?: number;
+    readonly freefraction?: number;
+    readonly availablefraction?: number;
+    readonly hugepages1g?: number;
+    readonly overcommitratio?: number;
+};
+/** Rounds a kB value down to the nearest 4 kB page boundary. */
+export declare function pagealign(kb: number): number;
+/**
+ * Generates a complete /proc/meminfo text for a machine with the requested
+ * total RAM. Every value is expressed in kB exactly like the kernel report:
+ * MemTotal, MemFree, MemAvailable, Buffers, Cached, the anon/file split,
+ * SwapTotal and SwapFree, slab accounting, commit accounting under
+ * vm.overcommit_memory=2 semantics, virtual memory areas, huge page state
+ * and the direct map breakdown.
+ *
+ * @param totalgb Total guest RAM in GB (positive number).
+ * @param options Optional swap size, vCPU count, fractions and huge pages.
+ */
+export declare function generateVirtualMeminfo(totalgb: number, options?: meminfoptions): string;
+/**
+ * Renders the minimal one-line meminfo shape absorbed from the v2 stub:
+ * a page-aligned MemTotal in kB for the requested capacity in MiB. The
+ * full 47-field payload comes from generateVirtualMeminfo.
+ */
+export declare function meminfoForMiB(mib: number): string;
+/**
+ * Docker memory-swap sentinel absorbed from the v2 stub: "-1" keeps swap
+ * unlimited, the value emitted by dockerMemoryFlags for every default plan.
+ */
+export declare const memorySwap = "-1";
+/**
+ * Docker /dev/shm size absorbed from the v2 stub: "2g" is the canonical
+ * fix for the PyTorch DataLoader bus error caused by the 64 MB default.
+ */
+export declare const shmSize = "2g";
+/**
+ * MemTotal anchor of the meminfo128g reference artifact: exactly
+ * 134217728 kB, the page-aligned total of 128 GiB. generatememinfo128g
+ * keeps the v5 parametric behavior of subtracting the 131072 kB firmware
+ * carveout, so its MemTotal reads 134086656 kB while this constant
+ * preserves the physical anchor captured on 2026-08-22.
+ */
+export declare const meminfo128gtotalkb = 134217728;
+/**
+ * Regenerates the full 47-field /proc/meminfo payload anchored at the
+ * meminfo128g artifact total (128 GiB, 134217728 kB) with the natural
+ * jitter of a live machine.
+ */
+export declare function generatememinfo128g(options?: meminfoptions): string;
+//# sourceMappingURL=virtualmemory.d.ts.map