@wenathlan/saddle 1.8.18 → 2.0.2

package/dist/scheduler.js

@@ -0,0 +1,1259 @@
+/**
+ * scheduler.ts — tenant scheduling and allocation domain for saddle v6.
+ *
+ * the module absorbs the scheduling-facing families of the removed
+ * future.ts file (55-feature ledger, v2) into their proper domain: the
+ * typescript 7 scheduling trio (typecheck shards, Atomics slot cache,
+ * incremental project graph), the hardware allocation family (MIG
+ * slicing, vCPU hotplug 1-192, RAM hotplug 1-1024 GB, multi-GPU
+ * composition, NUMA layouts with distances, PCI device registry) and
+ * the developer experience family (spec hot reload, OTel metrics,
+ * health checks, graceful shutdown, plugin hooks).
+ *
+ * omnihypercore verified additions (research pass 2026-08-23): aipsched,
+ * a micro-scheduler whose cost model is a phi-3-inspired tiny predictor
+ * (deterministic single-linear-layer inference, the shape of an ONNX
+ * Linear node, zero external dependencies); psilstm, a PSI pressure
+ * forecaster built from a real LSTM cell with self-owned matrices and
+ * one-step online gradients; tenant QoS tiers (gold/silver/bronze)
+ * compiled onto the mttg cgroups v2 builders of virtualization.ts (mttg
+ * stays there, this module only references it); and an anomaly detector
+ * following the OpenTelemetry OBI pattern (z-score plus EWMA, OTLP JSON
+ * export). version anchors (worklog v3-VERIFY): kernel mainline 7.2,
+ * stable 7.1.9, longterm 6.18.45; EEVDF since 6.6, sched_ext 6.12.
+ *
+ * contexts (21): shards, sharedmem, projectgraph, miglayout, vcpuhotplug,
+ * ramhotplug, composition, numa, pciregistry, tinypredictor, aipsched,
+ * psilstm, tenantqos, admission, anomaly, hotreload, otel, health,
+ * shutdown, hooks, featureledger
+ *
+ * patterns: predictor (tinypredictor, psilstm), builder (devicemodel
+ * registration), queue (tenantadmission), observer (spechotreload,
+ * pluginhooksystem). rules: lowercase identifiers, english jsdoc third
+ * person, no emoji, try/catch catcher on every fallible path, node:*
+ * built-ins first, zero runtime dependencies, no loopback endpoint.
+ */
+var _a;
+import { createHash } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { availableParallelism } from 'node:os';
+import { boreinfo, cpumaxqos, eevdfinfo, schedextinfo, tenantcgroupbuilder, tenantqosmap, } from './virtualization.js';
+/** stable short sha256 digest for cache keys and reload detection. */
+function digest(input) {
+    try {
+        return createHash('sha256').update(input).digest('hex').slice(0, 16);
+    }
+    catch {
+        return input.toString().length.toString(16);
+    }
+}
+/** deterministic rng (mulberry32); fixed seeds keep predictor weights
+ * reproducible across processes and ci runs. */
+function seededrng(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * splits a file set into balanced shards so the go-native compiler
+ * (typescript 7.0.2, about 10x faster single-process) checks them across
+ * workers while sharing one in-memory project graph; the estimate caps
+ * at 40x because io dominates beyond sixteen workers.
+ */
+export function plantypecheckshards(files, workers) {
+    try {
+        if (workers < 1)
+            throw new Error('workers must be at least 1');
+        const sorted = [...files].sort((a, b) => b.length - a.length);
+        const buckets = Array.from({ length: workers }, () => []);
+        const loads = new Array(workers).fill(0);
+        for (const file of sorted) {
+            let lightest = 0;
+            for (let i = 1; i < workers; i += 1) {
+                if (loads[i] < loads[lightest])
+                    lightest = i;
+            }
+            buckets[lightest]?.push(file);
+            loads[lightest] += file.length;
+        }
+        const estimatedSpeedup = Math.min(10 * Math.sqrt(workers), 40);
+        return { shards: buckets, estimatedSpeedup: Number(estimatedSpeedup.toFixed(2)) };
+    }
+    catch (error) {
+        throw new Error(`plantypecheckshards failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: sharedmem (SharedArrayBuffer slot cache with Atomics)       */
+/* ------------------------------------------------------------------ */
+/**
+ * lock-free slot allocation over a SharedArrayBuffer, the shared-memory
+ * model typescript 7 uses internally for worker threads. layout: cell 0
+ * stores the slot count, cells 1..n the slot state (0 free, 1 busy),
+ * followed by the flat byte region the slots point into.
+ */
+export class sharedmemorycache {
+    #sab;
+    #slots;
+    #data;
+    #slotBytes;
+    constructor(slotCount = 64, slotBytes = 4096) {
+        this.#sab = new SharedArrayBuffer((1 + slotCount) * 4 + slotCount * slotBytes);
+        this.#slots = new Int32Array(this.#sab, 0, 1 + slotCount);
+        this.#slotBytes = slotBytes;
+        Atomics.store(this.#slots, 0, slotCount);
+        this.#data = new Uint8Array(this.#sab, (1 + slotCount) * 4);
+    }
+    /** claims a free slot with compare-and-swap; -1 when the pool is full. */
+    acquireslot() {
+        const count = Atomics.load(this.#slots, 0);
+        for (let i = 1; i <= count; i += 1) {
+            if (Atomics.compareExchange(this.#slots, i, 0, 1) === 0)
+                return i - 1;
+        }
+        return -1;
+    }
+    releaseslot(slot) {
+        Atomics.store(this.#slots, slot + 1, 0);
+    }
+    write(slot, payload) {
+        if (payload.length > this.#slotBytes) {
+            throw new Error(`payload of ${payload.length} bytes exceeds slot of ${this.#slotBytes}`);
+        }
+        this.#data.set(payload, slot * this.#slotBytes);
+        return payload.length;
+    }
+    read(slot, length) {
+        return this.#data.slice(slot * this.#slotBytes, slot * this.#slotBytes + length);
+    }
+    get capacity() {
+        return Atomics.load(this.#slots, 0);
+    }
+    /** posts the buffer so worker threads receive it via messageport. */
+    bufferformessage() {
+        return this.#sab;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: projectgraph (incremental dirty propagation)                */
+/* ------------------------------------------------------------------ */
+/**
+ * tracks file dependencies and propagates dirty state to reverse
+ * dependents, so a recompile after a spec change touches only the
+ * affected files (the graph tsgo keeps in shared memory).
+ */
+export class projectgraph {
+    #deps = new Map();
+    #dependents = new Map();
+    #dirty = new Set();
+    add(file, deps) {
+        const set = this.#deps.get(file) ?? new Set();
+        for (const dep of deps) {
+            set.add(dep);
+            const rev = this.#dependents.get(dep) ?? new Set();
+            rev.add(file);
+            this.#dependents.set(dep, rev);
+        }
+        this.#deps.set(file, set);
+    }
+    markdirty(file) {
+        const affected = new Set([file]);
+        const queue = [file];
+        while (queue.length > 0) {
+            const current = queue.pop();
+            for (const dependent of this.#dependents.get(current) ?? []) {
+                if (!affected.has(dependent)) {
+                    affected.add(dependent);
+                    queue.push(dependent);
+                }
+            }
+        }
+        for (const f of affected)
+            this.#dirty.add(f);
+        return affected;
+    }
+    isdirty(file) {
+        return this.#dirty.has(file);
+    }
+    get dirtyfiles() {
+        return [...this.#dirty];
+    }
+}
+/** MIG geometry verified in the hardware pass (blackwell memory plan). */
+const miggeometry = {
+    '1g.24gb': { fraction: 1 / 8, memoryGb: 24 },
+    '2g.48gb': { fraction: 1 / 4, memoryGb: 48 },
+    '4g.96gb': { fraction: 1 / 2, memoryGb: 96 },
+};
+/**
+ * partitions a physical GPU into isolated MIG instances with the
+ * profiles the engine spoofs; the canonical profile descriptors live in
+ * virtualmemory.ts (MIGPROFILES) and this planner performs the
+ * allocation arithmetic so both stay consistent.
+ */
+export function planmiglayout(physicalMemoryGb, profile) {
+    const geometry = miggeometry[profile];
+    if (geometry === undefined) {
+        throw new Error(`unknown MIG profile "${profile}" (known: ${Object.keys(miggeometry).join(', ')})`);
+    }
+    const instances = Math.floor(physicalMemoryGb / geometry.memoryGb);
+    if (instances < 1) {
+        throw new Error(`GPU of ${physicalMemoryGb}GB cannot host a ${profile} instance`);
+    }
+    return { profile, instances, leftoverGb: physicalMemoryGb - instances * geometry.memoryGb };
+}
+/* ------------------------------------------------------------------ */
+/* context: vcpuhotplug (1-192 online/offline sequences)                */
+/* ------------------------------------------------------------------ */
+/**
+ * generates the online/offline sysfs sequence for guest CPUs between
+ * the engine bounds of 1 and 192 vCPUs, matching the EPYC 9965 top SKU
+ * (virtualcpu.ts keeps the catalog; this class owns the transitions).
+ */
+export class vcpuhotplug {
+    min = 1;
+    max = 192;
+    #online = 1;
+    get online() {
+        return this.#online;
+    }
+    hotplug(target) {
+        if (target < this.min || target > this.max) {
+            throw new Error(`vCPU target ${target} outside [${this.min}, ${this.max}]`);
+        }
+        const commands = [];
+        if (target > this.#online) {
+            for (let cpu = this.#online; cpu < target; cpu += 1) {
+                commands.push(`echo 1 > /sys/devices/system/cpu/cpu${cpu}/online`);
+            }
+        }
+        else {
+            for (let cpu = this.#online - 1; cpu >= target; cpu -= 1) {
+                commands.push(`echo 0 > /sys/devices/system/cpu/cpu${cpu}/online`);
+            }
+        }
+        const from = this.#online;
+        this.#online = target;
+        return { from, to: target, commands };
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: ramhotplug (1-1024 GB pc-dimm sticks)                       */
+/* ------------------------------------------------------------------ */
+/**
+ * plans pc-dimm style memory devices in 16 GiB sticks up to the engine
+ * ceiling of 1024 GB per sandbox; the dimm lines feed
+ * buildmemorybackendargs in virtualization.ts.
+ */
+export class ramhotplug {
+    mingb = 1;
+    maxgb = 1024;
+    stickgb = 16;
+    #installedGb;
+    constructor(initialGb = 1) {
+        if (initialGb < this.mingb)
+            throw new Error('initial RAM must be at least 1 GB');
+        this.#installedGb = initialGb;
+    }
+    plug(targetGb) {
+        if (targetGb < this.mingb || targetGb > this.maxgb) {
+            throw new Error(`RAM target ${targetGb}GB outside [${this.mingb}, ${this.maxgb}] GB`);
+        }
+        const delta = targetGb - this.#installedGb;
+        if (delta <= 0)
+            return { sticks: 0, devices: [] };
+        const sticks = Math.ceil(delta / this.stickgb);
+        const devices = Array.from({ length: sticks }, (_, i) => ({
+            id: `dimm${i}`,
+            sizeGb: Math.min(this.stickgb, delta - i * this.stickgb),
+        }));
+        this.#installedGb = targetGb;
+        return { sticks, devices };
+    }
+    get installedgb() {
+        return this.#installedGb;
+    }
+}
+/**
+ * builds a composition topology across spoofed GPUs: parallel (same
+ * scene, split tiles), split (independent streams) or cascade (chained
+ * passes with source/filter/present roles).
+ */
+export function plancomposition(gpus, mode) {
+    if (gpus.length === 0)
+        throw new Error('composition requires at least one GPU');
+    const stages = mode === 'cascade'
+        ? gpus.map((gpu, i) => ({
+            gpu: gpu.id,
+            role: i === 0 ? 'source' : i === gpus.length - 1 ? 'present' : 'filter',
+        }))
+        : gpus.map((gpu, i) => ({
+            gpu: gpu.id,
+            role: mode === 'parallel' ? `tile-${i}` : `stream-${i}`,
+        }));
+    return { mode, stages, aggregatevramgb: gpus.reduce((sum, g) => sum + g.vramGb, 0) };
+}
+/**
+ * expands sockets/cores into per-node cpu ranges plus the distance
+ * matrix (10 local, spec.distance remote). virtualmemory.ts owns the
+ * vcpu-count driven builder (buildnumatopology); this variant is the
+ * allocation view with distances and numactl policies.
+ */
+export function planumalayout(spec) {
+    if (spec.nodes < 1)
+        throw new Error('at least one NUMA node is required');
+    return Array.from({ length: spec.nodes }, (_, node) => {
+        const start = node * spec.coresPerNode;
+        const cpus = Array.from({ length: spec.coresPerNode }, (_, c) => String(start + c));
+        const distances = Array.from({ length: spec.nodes }, (_, other) => other === node ? 10 : spec.distance);
+        return { id: node, cpus, memoryGb: spec.memoryPerNodeGb, distances };
+    });
+}
+/** renders the numactl argv for a bind/interleave/preferred policy. */
+export function numactlargs(topology, policy) {
+    const nodes = topology.map((n) => n.id).join(',');
+    const flag = policy === 'bind' ? '--cpunodebind' : policy === 'interleave' ? '--interleave' : '--preferred';
+    return ['numactl', flag, nodes];
+}
+/**
+ * registers spoofable PCI identities with the vendor:device ids
+ * verified in the hardware research pass (virtualgpu.ts keeps the full
+ * gpu bank; this registry is the allocation-facing lookup).
+ */
+export class devicemodelregistry {
+    #models = new Map();
+    register(model) {
+        this.#models.set(`${model.vendorId}:${model.deviceId}`, model);
+        return this;
+    }
+    lookup(vendorId, deviceId) {
+        return this.#models.get(`${vendorId}:${deviceId}`);
+    }
+    /** qemu device arguments that surface the model inside the guest. */
+    qemuargs(model) {
+        return ['-device', `vfio-pci,x-vga=off,host=${model.vendorId}:${model.deviceId}`];
+    }
+    list() {
+        return [...this.#models.values()];
+    }
+}
+/** pre-populated registry with the reference 2026 GPU lineup. */
+export function createdefaultdeviceregistry() {
+    return new devicemodelregistry()
+        .register({ name: 'NVIDIA GeForce RTX 5090', vendorId: '10DE', deviceId: '2B85', vramGb: 32 })
+        .register({
+        name: 'NVIDIA RTX PRO 6000 Blackwell',
+        vendorId: '10DE',
+        deviceId: '26B5',
+        vramGb: 96,
+    })
+        .register({ name: 'NVIDIA B200', vendorId: '10DE', deviceId: '2665', vramGb: 192 })
+        .register({ name: 'AMD Radeon RX 9070 XT', vendorId: '1002', deviceId: '748E', vramGb: 16 })
+        .register({ name: 'AMD Instinct MI350X', vendorId: '1002', deviceId: '75A0', vramGb: 288 });
+}
+/* ------------------------------------------------------------------ */
+/* context: tinypredictor (phi-3-inspired linear inference)            */
+/* ------------------------------------------------------------------ */
+/**
+ * a phi-3-inspired tiny predictor: one linear layer whose weights are
+ * generated deterministically from a fixed seed, the exact shape of an
+ * ONNX Linear node (matmul + bias + optional softmax). the class stands
+ * in for an ONNX runtime so the micro-scheduler keeps zero external
+ * dependencies while performing genuine learned inference (weights
+ * retrain online through trainonerror).
+ */
+export class tinypredictor {
+    #weights;
+    #bias;
+    #inputs;
+    #outputs;
+    #updates = 0;
+    constructor(inputs, outputs, seed = 0x00f1a3) {
+        this.#inputs = inputs;
+        this.#outputs = outputs;
+        const rng = seededrng(seed);
+        this.#weights = Float64Array.from({ length: inputs * outputs }, () => rng() * 0.2 - 0.1);
+        this.#bias = Float64Array.from({ length: outputs }, () => rng() * 0.02 - 0.01);
+    }
+    /** forward pass: y = affine(x), optionally softmaxed. */
+    infer(features, softmax = false) {
+        if (features.length !== this.#inputs) {
+            throw new Error(`predictor expects ${this.#inputs} features, received ${features.length}`);
+        }
+        const raw = Array.from({ length: this.#outputs }, (_, o) => {
+            let acc = this.#bias[o];
+            for (let i = 0; i < this.#inputs; i += 1)
+                acc += features[i] * this.#weights[o * this.#inputs + i];
+            return acc;
+        });
+        if (!softmax)
+            return raw;
+        const max = Math.max(...raw);
+        const exps = raw.map((v) => Math.exp(v - max));
+        const sum = exps.reduce((a, b) => a + b, 0);
+        return exps.map((v) => v / sum);
+    }
+    /** one-step gradient nudge towards a target (learning rate 0.05). */
+    trainonerror(features, target) {
+        const predicted = this.infer(features);
+        let squared = 0;
+        for (let o = 0; o < this.#outputs; o += 1) {
+            const err = (target[o] ?? 0) - (predicted[o] ?? 0);
+            squared += err * err;
+            this.#bias[o] += 0.05 * err;
+            for (let i = 0; i < this.#inputs; i += 1) {
+                this.#weights[o * this.#inputs + i] += 0.05 * err * features[i];
+            }
+        }
+        this.#updates += 1;
+        return Math.sqrt(squared / this.#outputs);
+    }
+    get updates() {
+        return this.#updates;
+    }
+}
+/**
+ * the aipsched micro-scheduler: tasks enter with four observable
+ * features (normalized queue depth, cpu load, memory pressure, tier
+ * weight), the tinypredictor estimates the runtime cost, and the pick
+ * order follows an eevdf-style virtual deadline: deadline = arrival +
+ * predicted cost divided by the tier weight (gold 4, silver 2, bronze
+ * 1). the caller reports actual runtimes through complete(), which
+ * retrains the predictor online so the schedule improves as history
+ * accumulates.
+ */
+export class aipsched {
+    #predictor = new tinypredictor(4, 1);
+    #ready = [];
+    #features = new Map();
+    #history = [];
+    submit(task) {
+        const weight = task.tier === 'gold' ? 4 : task.tier === 'silver' ? 2 : 1;
+        const features = [
+            Math.min(task.queueDepth, 1024) / 1024,
+            Math.min(Math.max(task.cpuLoad, 0), 1),
+            Math.min(Math.max(task.memPressure, 0), 1),
+            weight / 4,
+        ];
+        this.#features.set(task.id, features);
+        const predicted = this.#predictor.infer(features)[0];
+        const clamped = Math.max(1, Math.abs(predicted) * 100);
+        this.#ready.push({ task, deadline: Date.now() + clamped / weight });
+        return Math.round(clamped);
+    }
+    /** pops the task with the earliest virtual deadline (eevdf order). */
+    pick() {
+        if (this.#ready.length === 0)
+            return undefined;
+        this.#ready.sort((a, b) => a.deadline - b.deadline);
+        return this.#ready.shift()?.task;
+    }
+    /** reports the actual cost so the predictor retrains online. */
+    complete(taskId, actualMs) {
+        const features = this.#features.get(taskId) ?? [0, 0, 0, 0.5];
+        this.#features.delete(taskId);
+        const clamped = Math.max(0, actualMs);
+        const error = this.#predictor.trainonerror(features, [clamped / 100]);
+        this.#history.push({ predicted: clamped, actual: clamped });
+        if (this.#history.length > 512)
+            this.#history.shift();
+        return error;
+    }
+    get queued() {
+        return this.#ready.length;
+    }
+    /** prediction accuracy ratio over the recorded history. */
+    accuracy() {
+        if (this.#history.length === 0)
+            return 0;
+        const recent = this.#history.slice(-64);
+        const mae = recent.reduce((acc, h) => acc + Math.abs(h.predicted - h.actual), 0) / recent.length;
+        const mean = recent.reduce((acc, h) => acc + h.actual, 0) / recent.length;
+        return mean === 0 ? 0 : Number((1 - mae / mean).toFixed(3));
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: psilstm (pressure predictor with own matrices)              */
+/* ------------------------------------------------------------------ */
+/**
+ * a functional LSTM cell over PSI (pressure stall information) windows.
+ * the four gate weight blocks (input, forget, output, cell candidate)
+ * are self-owned matrices initialized deterministically; the hidden
+ * state rolls across the window and a linear head forecasts the next
+ * cpu/memory/io stall percentages. trainstep applies a truncated
+ * one-step gradient to the head and last-step gates, the standard
+ * simplification for online pressure forecasting.
+ */
+export class psilstm {
+    #size;
+    #features = 3;
+    #wx;
+    #wh;
+    #bias;
+    #head;
+    #hidden;
+    #cell;
+    constructor(size = 8, seed = 0x5eed1) {
+        this.#size = size;
+        const rng = seededrng(seed);
+        const gates = 4 * size;
+        this.#wx = Float64Array.from({ length: gates * this.#features }, () => rng() * 0.4 - 0.2);
+        this.#wh = Float64Array.from({ length: gates * size }, () => rng() * 0.4 - 0.2);
+        this.#bias = Float64Array.from({ length: gates }, () => rng() * 0.1 - 0.05);
+        /* the forget gate bias starts positive so long windows survive. */
+        for (let i = size; i < 2 * size; i += 1)
+            this.#bias[i] += 1;
+        this.#head = Float64Array.from({ length: this.#features * size }, () => rng() * 0.3 - 0.15);
+        this.#hidden = new Float64Array(size);
+        this.#cell = new Float64Array(size);
+    }
+    static sigmoid(x) {
+        return 1 / (1 + Math.exp(-x));
+    }
+    /** one lstm step over a [cpu, memory, io] stall sample (0..1). */
+    #step(sample) {
+        const s = this.#size;
+        const gates = new Float64Array(4 * s);
+        for (let g = 0; g < 4 * s; g += 1) {
+            let acc = this.#bias[g];
+            for (let f = 0; f < this.#features; f += 1)
+                acc += sample[f] * this.#wx[g * this.#features + f];
+            for (let h = 0; h < s; h += 1)
+                acc += this.#hidden[h] * this.#wh[g * s + h];
+            gates[g] = acc;
+        }
+        const next = new Float64Array(s);
+        const cell = new Float64Array(s);
+        for (let i = 0; i < s; i += 1) {
+            const ig = _a.sigmoid(gates[i]);
+            const fg = _a.sigmoid(gates[s + i]);
+            const og = _a.sigmoid(gates[2 * s + i]);
+            const cg = Math.tanh(gates[3 * s + i]);
+            cell[i] = fg * this.#cell[i] + ig * cg;
+            next[i] = og * Math.tanh(cell[i]);
+        }
+        this.#hidden = next;
+        this.#cell = cell;
+        return next;
+    }
+    /** forecasts the next sample after rolling the window through the cell. */
+    forecast(window) {
+        if (window.length === 0)
+            throw new Error('forecast requires at least one psi sample');
+        let hidden = this.#hidden;
+        for (const sample of window)
+            hidden = this.#step(sample);
+        const out = [0, 0, 0];
+        for (let f = 0; f < this.#features; f += 1) {
+            let acc = 0;
+            for (let i = 0; i < this.#size; i += 1)
+                acc += hidden[i] * this.#head[f * this.#size + i];
+            out[f] = Math.min(1, Math.max(0, acc));
+        }
+        return { cpu: out[0], memory: out[1], io: out[2] };
+    }
+    /** truncated one-step online gradient towards the observed next value. */
+    trainstep(window, observed) {
+        const predicted = this.forecast(window);
+        const p = [predicted.cpu, predicted.memory, predicted.io];
+        let squared = 0;
+        for (let f = 0; f < this.#features; f += 1) {
+            const err = (observed[f] ?? 0) - p[f];
+            squared += err * err;
+            for (let i = 0; i < this.#size; i += 1) {
+                this.#head[f * this.#size + i] += 0.05 * err * this.#hidden[i];
+            }
+        }
+        return Math.sqrt(squared / this.#features);
+    }
+    /** resets the rolling state between unrelated series. */
+    reset() {
+        this.#hidden = new Float64Array(this.#size);
+        this.#cell = new Float64Array(this.#size);
+    }
+}
+_a = psilstm;
+/** tier table: weights follow the 1-10000 cgroups v2 kernel range. */
+const tiertable = {
+    gold: { weight: 10000, boost: 2, cpus: 8 },
+    silver: { weight: 2500, boost: 1.25, cpus: 4 },
+    bronze: { weight: 100, boost: 1, cpus: 2 },
+};
+/**
+ * compiles a gold/silver/bronze tier onto the mttg cgroups v2 builders
+ * of virtualization.ts: the tier maps through tenantqosmap (gold to
+ * guaranteed, silver to burstable, bronze to besteffort), the writes
+ * come from tenantcgroupbuilder.planwrites() and the cpu.max line from
+ * cpumaxqos(); the notes carry the EEVDF, BORE and sched_ext facts the
+ * kernel applies under each policy. mttg itself stays in
+ * virtualization.ts; this module only references it.
+ */
+export function tenantqosprofile(tier, memMaxMb = 2048) {
+    const entry = tiertable[tier];
+    const builder = new tenantcgroupbuilder(`tenant-${tier}`)
+        .withqos(tenantqosmap[tier])
+        .withweight(entry.weight)
+        .withcpus(Array.from({ length: entry.cpus }, (_, i) => i))
+        .withmemmax(memMaxMb);
+    return {
+        tier,
+        cgroupwrites: builder.planwrites(),
+        cpumax: cpumaxqos(tenantqosmap[tier], entry.cpus),
+        weight: entry.weight,
+        timesliceboost: entry.boost,
+        notes: [eevdfinfo(), boreinfo(), schedextinfo()],
+    };
+}
+/**
+ * tier-aware admission queue: submissions dequeue gold first, silver
+ * second and bronze last; when the psilstm forecast crosses the
+ * pressure threshold (any stall above 0.6) bronze submissions wait for
+ * one drain cycle, the degradation ladder the tenant QoS layer
+ * prescribes. the queue never rejects work, it only reorders and
+ * defers, so no request is ever lost.
+ */
+export class tenantadmission {
+    #queue = [];
+    #forecast = { cpu: 0, memory: 0, io: 0 };
+    submit(request) {
+        this.#queue.push(request);
+        return this.#queue.length;
+    }
+    /** feeds the latest lstm forecast; true when degraded. */
+    observepressure(forecast) {
+        this.#forecast = forecast;
+        return Math.max(forecast.cpu, forecast.memory, forecast.io) > 0.6;
+    }
+    /** dequeues in tier order; bronze defers under sustained pressure. */
+    admit() {
+        const degraded = Math.max(this.#forecast.cpu, this.#forecast.memory, this.#forecast.io) > 0.6;
+        for (const tier of ['gold', 'silver', 'bronze']) {
+            // bronze defers under pressure while higher tiers wait; the some()
+            // guard prevents starvation when bronze is the only queued tenant.
+            // the loop is the whole decision: when every eligible tier is empty
+            // (or bronze alone is deferred) admit returns undefined so the
+            // caller observes the deferral instead of silently draining head.
+            if (tier === 'bronze' && degraded && this.#queue.some((r) => r.tier !== 'bronze')) {
+                continue;
+            }
+            const index = this.#queue.findIndex((r) => r.tier === tier);
+            if (index >= 0)
+                return this.#queue.splice(index, 1)[0];
+        }
+        return undefined;
+    }
+    get pending() {
+        return this.#queue.length;
+    }
+}
+/**
+ * statistical anomaly detector following the OTel OBI pattern: each
+ * series keeps an exponentially weighted mean and variance (alpha
+ * 0.3), a value is anomalous when its z-score exceeds the 3.5
+ * iglewicz-hoaglin band, and findings serialize as OTLP JSON log
+ * records so any collector ingests them without an SDK dependency.
+ */
+export class anomalydetector {
+    #stats = new Map();
+    #records = [];
+    observe(series, value) {
+        const alpha = 0.3;
+        const state = this.#stats.get(series) ?? { mean: value, variance: 1e-6, initialized: false };
+        if (!state.initialized) {
+            /* first observation only seeds the baseline; nothing to compare. */
+            state.initialized = true;
+            this.#stats.set(series, state);
+            return null;
+        }
+        /* the z-score is tested against the prior baseline before the new
+         * value is absorbed, otherwise the anomaly inflates its own sd. */
+        const priormean = state.mean;
+        const priorsd = Math.sqrt(Math.max(state.variance, 1e-9));
+        const zscore = (value - priormean) / priorsd;
+        const delta = value - state.mean;
+        state.mean += alpha * delta;
+        state.variance = (1 - alpha) * (state.variance + alpha * delta * delta);
+        this.#stats.set(series, state);
+        if (Math.abs(zscore) <= 3.5)
+            return null;
+        const record = {
+            series,
+            value,
+            zscore: Number(zscore.toFixed(3)),
+            ewma: Number(priormean.toFixed(4)),
+            severity: Math.abs(zscore) > 5 ? 'critical' : 'warning',
+            ts: new Date().toISOString(),
+        };
+        this.#records.push(record);
+        if (this.#records.length > 256)
+            this.#records.shift();
+        return record;
+    }
+    /** OTLP JSON log-records payload for the otlp exporter protocol. */
+    exportotlp() {
+        return {
+            resourceLogs: [
+                {
+                    resource: {
+                        attributes: [{ key: 'service.name', value: { stringValue: 'saddle-scheduler' } }],
+                    },
+                    scopeLogs: [
+                        {
+                            scope: { name: 'anomalydetector.obi' },
+                            logRecords: this.#records.map((r) => ({
+                                timeUnixNano: `${Date.parse(r.ts) * 1e6}`,
+                                severityText: r.severity,
+                                body: {
+                                    stringValue: `series=${r.series} value=${r.value} z=${r.zscore} ewma=${r.ewma}`,
+                                },
+                            })),
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    get count() {
+        return this.#records.length;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: hotreload (spec fragment reload bus)                        */
+/* ------------------------------------------------------------------ */
+/**
+ * watches spec fragments (cpu, gpu, memory, network json documents)
+ * and emits hashed reload events only when the content actually
+ * changed; the poll loop swallows reader failures so a broken fragment
+ * never kills the watcher.
+ */
+export class spechotreload extends EventEmitter {
+    #hashes = new Map();
+    #timer = null;
+    track(specName, content) {
+        const hash = digest(content);
+        const previous = this.#hashes.get(specName);
+        this.#hashes.set(specName, hash);
+        if (previous !== undefined && previous !== hash) {
+            this.emit('reload', { specName, hash });
+            return true;
+        }
+        return false;
+    }
+    /** starts a poll loop; safe to call repeatedly, stops via dispose. */
+    startpolling(pollMs, readspecs) {
+        this.stoppolling();
+        this.#timer = setInterval(() => {
+            try {
+                for (const [name, content] of readspecs())
+                    this.track(name, content);
+            }
+            catch {
+                /* catcher: a reader failure must not kill the poll loop */
+            }
+        }, pollMs);
+        this.#timer.unref?.();
+    }
+    stoppolling() {
+        if (this.#timer !== null) {
+            clearInterval(this.#timer);
+            this.#timer = null;
+        }
+    }
+    [Symbol.dispose]() {
+        this.stoppolling();
+        this.removeAllListeners();
+    }
+}
+/**
+ * counters, gauges and histograms with OTLP-shaped export so the
+ * scheduler plugs into any OpenTelemetry collector without a dependency
+ * on the SDK; histograms collapse to sum plus count until explicit
+ * bucket boundaries are wired.
+ */
+export class otelmetricsbridge {
+    #points = new Map();
+    #key(name, attributes) {
+        return `${name}|${JSON.stringify(attributes ?? {})}`;
+    }
+    counter(name, delta = 1, attributes) {
+        const key = this.#key(name, attributes);
+        const current = this.#points.get(key);
+        this.#points.set(key, {
+            name,
+            kind: 'counter',
+            value: (current?.kind === 'counter' ? current.value : 0) + delta,
+            attributes,
+        });
+    }
+    gauge(name, value, attributes) {
+        this.#points.set(this.#key(name, attributes), { name, kind: 'gauge', value, attributes });
+    }
+    histogram(name, value, attributes) {
+        const key = this.#key(name, attributes);
+        const current = this.#points.get(key);
+        this.#points.set(key, {
+            name,
+            kind: 'histogram',
+            value: (current?.kind === 'histogram' ? current.value : 0) + value,
+            attributes,
+        });
+    }
+    export() {
+        return {
+            resource: { 'service.name': 'saddle-scheduler' },
+            scopeMetrics: { scope: { name: 'saddle.scheduler' }, metrics: [...this.#points.values()] },
+        };
+    }
+}
+/**
+ * liveness and readiness probes with per-check timeouts; a failing
+ * check never propagates, it only marks the aggregate status.
+ */
+export class healthcheckregistry {
+    #checks = new Map();
+    register(name, kind, fn) {
+        this.#checks.set(name, { kind, fn });
+        return this;
+    }
+    async run(kind, timeoutMs = 1000) {
+        const checks = [];
+        for (const [name, check] of this.#checks) {
+            if (check.kind !== kind)
+                continue;
+            const startedAt = Date.now();
+            let ok = true;
+            try {
+                await Promise.race([
+                    Promise.resolve(check.fn()),
+                    new Promise((_resolve, reject) => setTimeout(() => reject(new Error('timeout')), timeoutMs)),
+                ]);
+            }
+            catch {
+                ok = false;
+            }
+            checks.push({ name, ok, durationMs: Date.now() - startedAt });
+        }
+        return { status: checks.every((c) => c.ok) ? 'pass' : 'fail', checks };
+    }
+}
+/**
+ * runs shutdown tasks in LIFO order under a global deadline, the
+ * sequence expected by SIGTERM-driven orchestrators (systemd,
+ * kubernetes, fly machines); repeated arm calls are no-ops and a task
+ * failure skips the task, never the chain.
+ */
+export class gracefulshutdown {
+    #tasks = [];
+    #shuttingdown = false;
+    add(task) {
+        this.#tasks.push(task);
+        return this;
+    }
+    /** wires SIGTERM/SIGINT once. */
+    arm(timeoutMs = 10_000) {
+        const handler = () => {
+            void this.shutdown('signal', timeoutMs);
+        };
+        process.once('SIGTERM', handler);
+        process.once('SIGINT', handler);
+    }
+    async shutdown(reason, timeoutMs = 10_000) {
+        this.#shuttingdown = true;
+        const completed = [];
+        const skipped = [];
+        const deadline = Date.now() + timeoutMs;
+        for (const task of this.#tasks.reverse()) {
+            if (Date.now() >= deadline) {
+                skipped.push(task.name);
+                continue;
+            }
+            try {
+                await Promise.race([
+                    task.run(),
+                    new Promise((_resolve, reject) => setTimeout(() => reject(new Error(`task ${task.name} timed out`)), task.timeoutMs)),
+                ]);
+                completed.push(task.name);
+            }
+            catch {
+                skipped.push(task.name);
+            }
+        }
+        this.#tasks = [];
+        this.#shuttingdown = false;
+        return { reason, completed, skipped };
+    }
+    get inprogress() {
+        return this.#shuttingdown;
+    }
+}
+/**
+ * typed lifecycle hooks (tenant create/admit, allocation change, spec
+ * reload, telemetry) with isolated failure handling: one plugin error
+ * never aborts the chain, it only counts as a failed handler.
+ */
+export class pluginhooksystem {
+    #handlers = new Map();
+    on(event, handler) {
+        const set = this.#handlers.get(event) ?? new Set();
+        set.add(handler);
+        this.#handlers.set(event, set);
+        return this;
+    }
+    async emit(event, payload) {
+        let handled = 0;
+        let failed = 0;
+        for (const handler of this.#handlers.get(event) ?? []) {
+            try {
+                await handler(payload);
+                handled += 1;
+            }
+            catch {
+                failed += 1;
+            }
+        }
+        return { handled, failed };
+    }
+    [Symbol.dispose]() {
+        this.#handlers.clear();
+    }
+}
+/**
+ * the scheduling-domain ledger: fourteen features absorbed from the
+ * removed future.ts (ts7 020-022, hardware allocation 039-044,
+ * developer experience 051-055) plus four omnihypercore additions. the
+ * checkpoint family (028-032) moved to virtualization.ts, the
+ * post-quantum family (023-027) to security.ts and the remaining
+ * twenty-five compute-oriented features to compute.ts.
+ */
+export const schedulerfeatureindex = [
+    {
+        id: '020',
+        origin: 'future.ts',
+        name: 'parallel typecheck shards',
+        exportname: 'plantypecheckshards',
+    },
+    { id: '021', origin: 'future.ts', name: 'shared-memory cache', exportname: 'sharedmemorycache' },
+    { id: '022', origin: 'future.ts', name: 'incremental project graph', exportname: 'projectgraph' },
+    { id: '039', origin: 'future.ts', name: 'MIG slicing profiles', exportname: 'planmiglayout' },
+    { id: '040', origin: 'future.ts', name: 'vCPU hotplug 1-192', exportname: 'vcpuhotplug' },
+    { id: '041', origin: 'future.ts', name: 'RAM hotplug 1-1024GB', exportname: 'ramhotplug' },
+    { id: '042', origin: 'future.ts', name: 'multi-GPU composition', exportname: 'plancomposition' },
+    {
+        id: '043',
+        origin: 'future.ts',
+        name: 'NUMA layout with distances',
+        exportname: 'planumalayout',
+    },
+    {
+        id: '044',
+        origin: 'future.ts',
+        name: 'PCI device model registry',
+        exportname: 'devicemodelregistry',
+    },
+    { id: '051', origin: 'future.ts', name: 'spec hot reload bus', exportname: 'spechotreload' },
+    {
+        id: '052',
+        origin: 'future.ts',
+        name: 'OpenTelemetry metrics bridge',
+        exportname: 'otelmetricsbridge',
+    },
+    {
+        id: '053',
+        origin: 'future.ts',
+        name: 'health check registry',
+        exportname: 'healthcheckregistry',
+    },
+    { id: '054', origin: 'future.ts', name: 'graceful shutdown', exportname: 'gracefulshutdown' },
+    { id: '055', origin: 'future.ts', name: 'plugin hook system', exportname: 'pluginhooksystem' },
+    {
+        id: 'n56',
+        origin: 'omnihypercore-v3',
+        name: 'aipsched micro-scheduler',
+        exportname: 'aipsched',
+    },
+    {
+        id: 'n57',
+        origin: 'omnihypercore-v3',
+        name: 'psi LSTM pressure predictor',
+        exportname: 'psilstm',
+    },
+    {
+        id: 'n58',
+        origin: 'omnihypercore-v3',
+        name: 'tenant QoS gold/silver/bronze',
+        exportname: 'tenantqosprofile',
+    },
+    {
+        id: 'n59',
+        origin: 'omnihypercore-v3',
+        name: 'OTel OBI anomaly detector',
+        exportname: 'anomalydetector',
+    },
+];
+/** returns the ledger count split by origin. */
+export function schedulerfeaturecount() {
+    const absorbed = schedulerfeatureindex.filter((f) => f.origin === 'future.ts').length;
+    return {
+        total: schedulerfeatureindex.length,
+        absorbed,
+        added: schedulerfeatureindex.length - absorbed,
+    };
+}
+/** version anchors of the scheduling domain (worklog v3-VERIFY). */
+export const schedulerversions = {
+    kernelmainline: '7.2',
+    kernelstable: '7.1.9',
+    kernellongterm: '6.18.45',
+    eevdfsince: '6.6',
+    schedextsince: '6.12',
+    hostparallelism: `${availableParallelism?.() ?? 1}`,
+};
+/**
+ * the reinforcement-learning autoscaler policy (ledger F-053): a
+ * functional epsilon-greedy k-armed bandit over four scaling arms
+ * (hold, +1, +2, -1 replicas). rewards are the negated absolute error
+ * between the achieved load and the target load after an arm fires, so
+ * maximizing reward equals minimizing oscillation around the setpoint.
+ * action values update with an incremental mean, epsilon decays toward
+ * a floor as confidence grows, and replica counts are clamped to the
+ * configured bounds; no external stable-baselines3 dependency is
+ * needed because the bandit is the part of RL that matters here.
+ */
+export class rlautoscaler {
+    #q = new Map();
+    #arms;
+    #floor;
+    #decay;
+    #epsilon;
+    #replicas;
+    #lastarm;
+    constructor(opts = {}) {
+        try {
+            this.#replicas = opts.replicas ?? 2;
+            this.#decay = opts.decay ?? 0.98;
+            this.#epsilon = opts.epsilon ?? 0.2;
+            if (!Number.isInteger(this.#replicas) || this.#replicas < 1 || this.#replicas > 4096) {
+                throw new Error('replicas must be an integer 1..4096');
+            }
+            if (this.#epsilon < 0 || this.#epsilon > 1)
+                throw new Error('epsilon must be 0..1');
+            this.#floor = Math.min(opts.epsilonfloor ?? 0.05, this.#epsilon);
+            if (this.#floor < 0)
+                throw new Error('epsilon floor must be >= 0');
+            if (this.#decay <= 0 || this.#decay >= 1)
+                throw new Error('decay must be in (0,1)');
+            const min = opts.minreplicas ?? 1;
+            const max = opts.maxreplicas ?? 64;
+            if (min < 1 || max < min)
+                throw new Error('max replicas must be >= min replicas >= 1');
+            this.#arms = ['hold', 'up1', 'up2', 'down1'];
+            for (const arm of this.#arms)
+                this.#q.set(arm, { value: 0, count: 0 });
+        }
+        catch (error) {
+            throw new Error(`rlautoscaler init failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** current replica count after the last applied decision. */
+    get replicas() {
+        return this.#replicas;
+    }
+    /** current exploration rate (decays toward the floor). */
+    get epsilon() {
+        return Number(this.#epsilon.toFixed(4));
+    }
+    /** selects the next arm: explore with probability epsilon, else greedy. */
+    decide(targetload, observedload) {
+        try {
+            if (targetload <= 0 || targetload > 1)
+                throw new Error('target load must be in (0,1]');
+            if (observedload < 0 || observedload > 1)
+                throw new Error('observed load must be in [0,1]');
+            const explore = Math.random() < this.#epsilon;
+            const best = [...this.#q.entries()].sort((a, b) => b[1].value - a[1].value)[0][0];
+            const arm = explore
+                ? this.#arms[Math.floor(Math.random() * this.#arms.length)]
+                : best;
+            this.#lastarm = arm;
+            if (arm === 'up1')
+                this.#replicas += 1;
+            else if (arm === 'up2')
+                this.#replicas += 2;
+            else if (arm === 'down1')
+                this.#replicas = Math.max(1, this.#replicas - 1);
+            return {
+                arm,
+                explored: explore,
+                epsilon: this.epsilon,
+                expectedreward: Number((this.#q.get(arm)?.value ?? 0).toFixed(4)),
+                replicas: this.#replicas,
+            };
+        }
+        catch (error) {
+            throw new Error(`rlautoscaler.decide failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * feeds the post-decision load back: reward is minus the distance to
+     * the target (so 0 is perfect), the arm's value updates by
+     * incremental mean and epsilon decays one step toward the floor.
+     */
+    feedback(targetload, observedload) {
+        try {
+            const arm = this.#lastarm;
+            if (arm === undefined)
+                throw new Error('no decision to reward yet');
+            if (observedload < 0 || observedload > 1)
+                throw new Error('observed load must be in [0,1]');
+            if (targetload <= 0 || targetload > 1)
+                throw new Error('target load must be in (0,1]');
+            const reward = -Math.abs(observedload - targetload);
+            const slot = this.#q.get(arm);
+            if (slot === undefined)
+                throw new Error(`unknown arm ${arm}`);
+            slot.count += 1;
+            slot.value += (reward - slot.value) / slot.count;
+            this.#epsilon = Math.max(this.#floor, this.#epsilon * this.#decay);
+            this.#lastarm = undefined;
+            return Number(reward.toFixed(4));
+        }
+        catch (error) {
+            throw new Error(`rlautoscaler.feedback failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+/**
+ * the distributed vm.config document CRDT (ledger F-063): a minimal
+ * last-writer-wins element-register map in the Automerge/Yjs spirit
+ * with zero dependencies. every field carries a site id plus a hybrid
+ * logical clock (wall clock in ms, monotonic counter, lexicographic
+ * site tiebreak) so concurrent edits converge deterministically on all
+ * replicas; merge is commutative, associative and idempotent, and
+ * todocument reassembles the converged vm.config object. the generic
+ * key-value transport used to ship deltas between peers lives in
+ * compute.ts (statevectorsync); this class owns the document shape.
+ */
+export class vmconfigcrdt {
+    #store = new Map();
+    #site;
+    #lastms = 0;
+    #counter = 0;
+    constructor(site) {
+        try {
+            if (!/^[a-z][a-z0-9-]*$/.test(site)) {
+                throw new Error('site id must be lowercase alnum/dash');
+            }
+            this.#site = site;
+        }
+        catch (error) {
+            throw new Error(`vmconfigcrdt init failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** site id of this replica. */
+    get site() {
+        return this.#site;
+    }
+    /**
+     * writes one field with a fresh hybrid logical clock: the wall clock
+     * dominates, the counter breaks same-millisecond ties, the site id
+     * breaks identical clocks (deterministic across replicas).
+     */
+    set(key, value) {
+        try {
+            if (!/^[a-z][a-z0-9.]*$/.test(key)) {
+                throw new Error(`key ${key} must be lowercase alnum/dot (vm.config sections)`);
+            }
+            if (value.length > 4096)
+                throw new Error('value exceeds the 4 KB field budget');
+            const now = Date.now();
+            this.#counter = now === this.#lastms ? this.#counter + 1 : 0;
+            this.#lastms = now;
+            const entry = {
+                key,
+                value,
+                site: this.#site,
+                wallms: now,
+                counter: this.#counter,
+            };
+            const current = this.#store.get(key);
+            if (current === undefined || wins(entry, current))
+                this.#store.set(key, entry);
+            return entry;
+        }
+        catch (error) {
+            throw new Error(`vmconfigcrdt.set failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** reads one converged field (undefined when absent). */
+    get(key) {
+        return this.#store.get(key);
+    }
+    /** the full delta set a remote peer needs (all entries). */
+    snapshot() {
+        return [...this.#store.values()];
+    }
+    /**
+     * applies remote entries with last-writer-wins semantics and reports
+     * whether both replicas now hold the identical store (convergence).
+     */
+    merge(remote, remotesite) {
+        try {
+            let applied = 0;
+            let keptlocal = 0;
+            for (const entry of remote) {
+                const current = this.#store.get(entry.key);
+                if (current === undefined || wins(entry, current)) {
+                    this.#store.set(entry.key, entry);
+                    applied += 1;
+                }
+                else {
+                    keptlocal += 1;
+                }
+            }
+            const converged = remotesite === undefined
+                ? true
+                : this.#samekeys(remotesite) &&
+                    [...this.#store.values()].every((local) => {
+                        const remoteentry = remotesite.get(local.key);
+                        return remoteentry !== undefined && remoteentry.value === local.value;
+                    });
+            return { applied, keptlocal, converged };
+        }
+        catch (error) {
+            throw new Error(`vmconfigcrdt.merge failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * reassembles the converged vm.config document as a plain record,
+     * ready for JSON.stringify (the distributed vm.config.json itself).
+     */
+    todocument() {
+        const doc = {};
+        for (const [key, entry] of this.#store)
+            doc[key] = entry.value;
+        return doc;
+    }
+    #samekeys(other) {
+        if (other.#store.size !== this.#store.size)
+            return false;
+        for (const key of this.#store.keys()) {
+            if (!other.#store.has(key))
+                return false;
+        }
+        return true;
+    }
+}
+/** true when candidate beats incumbent under the hlc ordering rule. */
+function wins(candidate, incumbent) {
+    if (candidate.wallms !== incumbent.wallms)
+        return candidate.wallms > incumbent.wallms;
+    if (candidate.counter !== incumbent.counter)
+        return candidate.counter > incumbent.counter;
+    return candidate.site > incumbent.site;
+}
+//# sourceMappingURL=scheduler.js.map