@wenathlan/saddle 1.8.17 → 2.0.2

package/scheduler.ts

@@ -0,0 +1,1600 @@
+/**
+ * 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.
+ */
+
+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: string | Uint8Array): string {
+  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: number): () => number {
+  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;
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* context: shards (parallel typecheck sharding for tsgo)               */
+/* ------------------------------------------------------------------ */
+
+/** balanced shard plan for the go-native typescript 7 compiler. */
+export interface shardplan {
+  readonly shards: readonly (readonly string[])[];
+  readonly estimatedSpeedup: number;
+}
+
+/**
+ * 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: readonly string[], workers: number): shardplan {
+  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: string[][] = Array.from({ length: workers }, () => []);
+    const loads = new Array<number>(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 {
+  readonly #sab: SharedArrayBuffer;
+  readonly #slots: Int32Array;
+  readonly #data: Uint8Array;
+  readonly #slotBytes: number;
+
+  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(): number {
+    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: number): void {
+    Atomics.store(this.#slots, slot + 1, 0);
+  }
+
+  write(slot: number, payload: Uint8Array): number {
+    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: number, length: number): Uint8Array {
+    return this.#data.slice(slot * this.#slotBytes, slot * this.#slotBytes + length);
+  }
+
+  get capacity(): number {
+    return Atomics.load(this.#slots, 0);
+  }
+
+  /** posts the buffer so worker threads receive it via messageport. */
+  bufferformessage(): SharedArrayBuffer {
+    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<string, Set<string>>();
+  #dependents = new Map<string, Set<string>>();
+  #dirty = new Set<string>();
+
+  add(file: string, deps: readonly string[]): void {
+    const set = this.#deps.get(file) ?? new Set<string>();
+    for (const dep of deps) {
+      set.add(dep);
+      const rev = this.#dependents.get(dep) ?? new Set<string>();
+      rev.add(file);
+      this.#dependents.set(dep, rev);
+    }
+    this.#deps.set(file, set);
+  }
+
+  markdirty(file: string): Set<string> {
+    const affected = new Set<string>([file]);
+    const queue = [file];
+    while (queue.length > 0) {
+      const current = queue.pop() as string;
+      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: string): boolean {
+    return this.#dirty.has(file);
+  }
+
+  get dirtyfiles(): readonly string[] {
+    return [...this.#dirty];
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: miglayout (GPU MIG slicing allocation)                      */
+/* ------------------------------------------------------------------ */
+
+/** one MIG partitioning result: profile, instance count and leftover
+ * (named miglayoutplan to stay distinct from the virtualgpu.ts
+ * miglayout geometry type). */
+export interface miglayoutplan {
+  readonly profile: string;
+  readonly instances: number;
+  readonly leftoverGb: number;
+}
+
+/** MIG geometry verified in the hardware pass (blackwell memory plan). */
+const miggeometry: Readonly<Record<string, { fraction: number; memoryGb: number }>> = {
+  '1g.24gb': { fraction: 1 / 8, memoryGb: 24 },
+  '2g.48gb': { fraction: 1 / 4, memoryGb: 48 },
+  '4g.96gb': { fraction: 1 / 2, memoryGb: 96 },
+} as const;
+
+/**
+ * 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: number, profile: string): miglayoutplan {
+  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 {
+  readonly min = 1;
+  readonly max = 192;
+  #online = 1;
+
+  get online(): number {
+    return this.#online;
+  }
+
+  hotplug(target: number): { from: number; to: number; commands: readonly string[] } {
+    if (target < this.min || target > this.max) {
+      throw new Error(`vCPU target ${target} outside [${this.min}, ${this.max}]`);
+    }
+    const commands: string[] = [];
+    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 {
+  readonly mingb = 1;
+  readonly maxgb = 1024;
+  readonly stickgb = 16;
+  #installedGb: number;
+
+  constructor(initialGb = 1) {
+    if (initialGb < this.mingb) throw new Error('initial RAM must be at least 1 GB');
+    this.#installedGb = initialGb;
+  }
+
+  plug(targetGb: number): { sticks: number; devices: readonly { id: string; sizeGb: number }[] } {
+    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(): number {
+    return this.#installedGb;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: composition (multi-GPU topology)                            */
+/* ------------------------------------------------------------------ */
+
+/** one attachable GPU unit. */
+export interface gpuunit {
+  readonly id: string;
+  readonly model: string;
+  readonly vramGb: number;
+}
+
+/** composition result across the attached units. */
+export interface compositionlayout {
+  readonly mode: 'parallel' | 'split' | 'cascade';
+  readonly stages: readonly { gpu: string; role: string }[];
+  readonly aggregatevramgb: number;
+}
+
+/**
+ * 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: readonly gpuunit[],
+  mode: compositionlayout['mode'],
+): compositionlayout {
+  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) };
+}
+
+/* ------------------------------------------------------------------ */
+/* context: numa (topology, distances, numactl)                         */
+/* ------------------------------------------------------------------ */
+
+/** one NUMA node with cpu ranges and a distance row. */
+export interface numanode {
+  readonly id: number;
+  readonly cpus: readonly string[];
+  readonly memoryGb: number;
+  readonly distances: readonly number[];
+}
+
+/**
+ * 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: {
+  nodes: number;
+  coresPerNode: number;
+  memoryPerNodeGb: number;
+  distance: number;
+}): readonly numanode[] {
+  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: readonly numanode[],
+  policy: 'bind' | 'interleave' | 'preferred',
+): readonly string[] {
+  const nodes = topology.map((n) => n.id).join(',');
+  const flag =
+    policy === 'bind' ? '--cpunodebind' : policy === 'interleave' ? '--interleave' : '--preferred';
+  return ['numactl', flag, nodes];
+}
+
+/* ------------------------------------------------------------------ */
+/* context: pciregistry (spoofable PCI identities)                      */
+/* ------------------------------------------------------------------ */
+
+/** one spoofable PCI device model with real vendor:device ids. */
+export interface devicemodel {
+  readonly name: string;
+  readonly vendorId: string;
+  readonly deviceId: string;
+  readonly vramGb: number;
+}
+
+/**
+ * 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<string, devicemodel>();
+
+  register(model: devicemodel): this {
+    this.#models.set(`${model.vendorId}:${model.deviceId}`, model);
+    return this;
+  }
+
+  lookup(vendorId: string, deviceId: string): devicemodel | undefined {
+    return this.#models.get(`${vendorId}:${deviceId}`);
+  }
+
+  /** qemu device arguments that surface the model inside the guest. */
+  qemuargs(model: devicemodel): readonly string[] {
+    return ['-device', `vfio-pci,x-vga=off,host=${model.vendorId}:${model.deviceId}`];
+  }
+
+  list(): readonly devicemodel[] {
+    return [...this.#models.values()];
+  }
+}
+
+/** pre-populated registry with the reference 2026 GPU lineup. */
+export function createdefaultdeviceregistry(): devicemodelregistry {
+  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 {
+  readonly #weights: Float64Array;
+  readonly #bias: Float64Array;
+  readonly #inputs: number;
+  readonly #outputs: number;
+  #updates = 0;
+
+  constructor(inputs: number, outputs: number, 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: readonly number[], softmax = false): readonly number[] {
+    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: readonly number[], target: readonly number[]): number {
+    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(): number {
+    return this.#updates;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: aipsched (micro-scheduler with predicted cost)              */
+/* ------------------------------------------------------------------ */
+
+/** one schedulable task with tenant tier and observable load features. */
+export interface schedtask {
+  readonly id: string;
+  readonly tier: 'gold' | 'silver' | 'bronze';
+  readonly queueDepth: number;
+  readonly cpuLoad: number;
+  readonly memPressure: number;
+}
+
+/**
+ * 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 {
+  readonly #predictor = new tinypredictor(4, 1);
+  #ready: { task: schedtask; deadline: number }[] = [];
+  #features = new Map<string, readonly number[]>();
+  #history: { predicted: number; actual: number }[] = [];
+
+  submit(task: schedtask): number {
+    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(): schedtask | undefined {
+    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: string, actualMs: number): number {
+    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(): number {
+    return this.#ready.length;
+  }
+
+  /** prediction accuracy ratio over the recorded history. */
+  accuracy(): number {
+    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 {
+  readonly #size: number;
+  readonly #features = 3;
+  readonly #wx: Float64Array;
+  readonly #wh: Float64Array;
+  readonly #bias: Float64Array;
+  readonly #head: Float64Array;
+  #hidden: Float64Array;
+  #cell: Float64Array;
+
+  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: number): number {
+    return 1 / (1 + Math.exp(-x));
+  }
+
+  /** one lstm step over a [cpu, memory, io] stall sample (0..1). */
+  #step(sample: readonly number[]): Float64Array {
+    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 = psilstm.sigmoid(gates[i]);
+      const fg = psilstm.sigmoid(gates[s + i]);
+      const og = psilstm.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: readonly (readonly number[])[]): { cpu: number; memory: number; io: number } {
+    if (window.length === 0) throw new Error('forecast requires at least one psi sample');
+    let hidden: Float64Array = 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: readonly (readonly number[])[], observed: readonly number[]): number {
+    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(): void {
+    this.#hidden = new Float64Array(this.#size);
+    this.#cell = new Float64Array(this.#size);
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: tenantqos (gold/silver/bronze tiers onto mttg cgroups)      */
+/* ------------------------------------------------------------------ */
+
+/** the three external tenant tiers (mttg adds the internal idle class). */
+export type tenanttier = 'gold' | 'silver' | 'bronze';
+
+/** one compiled tier profile: cgroup writes plus scheduler policy. */
+export interface tenantqosprofile {
+  readonly tier: tenanttier;
+  readonly cgroupwrites: readonly { readonly file: string; readonly content: string }[];
+  readonly cpumax: string;
+  readonly weight: number;
+  readonly timesliceboost: number;
+  readonly notes: readonly string[];
+}
+
+/** tier table: weights follow the 1-10000 cgroups v2 kernel range. */
+const tiertable: Readonly<Record<tenanttier, { weight: number; boost: number; cpus: number }>> = {
+  gold: { weight: 10000, boost: 2, cpus: 8 },
+  silver: { weight: 2500, boost: 1.25, cpus: 4 },
+  bronze: { weight: 100, boost: 1, cpus: 2 },
+} as const;
+
+/**
+ * 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: tenanttier, memMaxMb = 2048): tenantqosprofile {
+  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()],
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* context: admission (tier-aware queue with psi degradation)           */
+/* ------------------------------------------------------------------ */
+
+/** one admission request pending a tier decision. */
+export interface admissionrequest {
+  readonly id: string;
+  readonly tier: tenanttier;
+  readonly workloadName: string;
+}
+
+/**
+ * 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: admissionrequest[] = [];
+  #forecast: { cpu: number; memory: number; io: number } = { cpu: 0, memory: 0, io: 0 };
+
+  submit(request: admissionrequest): number {
+    this.#queue.push(request);
+    return this.#queue.length;
+  }
+
+  /** feeds the latest lstm forecast; true when degraded. */
+  observepressure(forecast: { cpu: number; memory: number; io: number }): boolean {
+    this.#forecast = forecast;
+    return Math.max(forecast.cpu, forecast.memory, forecast.io) > 0.6;
+  }
+
+  /** dequeues in tier order; bronze defers under sustained pressure. */
+  admit(): admissionrequest | undefined {
+    const degraded = Math.max(this.#forecast.cpu, this.#forecast.memory, this.#forecast.io) > 0.6;
+    for (const tier of ['gold', 'silver', 'bronze'] as const) {
+      // 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(): number {
+    return this.#queue.length;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: anomaly (z-score + EWMA detector, OTLP OBI export)          */
+/* ------------------------------------------------------------------ */
+
+/** one detected anomaly in the OpenTelemetry OBI (observability for
+ * intelligent agents) record shape. */
+export interface anomalyrecord {
+  readonly series: string;
+  readonly value: number;
+  readonly zscore: number;
+  readonly ewma: number;
+  readonly severity: 'warning' | 'critical';
+  readonly ts: string;
+}
+
+/** one OTLP JSON log record (the exporter protocol shape). */
+export interface otlplogrecord {
+  readonly timeUnixNano: string;
+  readonly severityText: string;
+  readonly body: { stringValue: string };
+}
+
+/**
+ * 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<string, { mean: number; variance: number; initialized: boolean }>();
+  #records: anomalyrecord[] = [];
+
+  observe(series: string, value: number): anomalyrecord | null {
+    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: anomalyrecord = {
+      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(): {
+    resourceLogs: {
+      resource: { attributes: { key: string; value: { stringValue: string } }[] };
+      scopeLogs: { scope: { name: string }; logRecords: readonly otlplogrecord[] }[];
+    }[];
+  } {
+    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(): number {
+    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<string, string>();
+  #timer: NodeJS.Timeout | null = null;
+
+  track(specName: string, content: string): boolean {
+    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: number, readspecs: () => Iterable<[string, string]>): void {
+    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(): void {
+    if (this.#timer !== null) {
+      clearInterval(this.#timer);
+      this.#timer = null;
+    }
+  }
+
+  [Symbol.dispose](): void {
+    this.stoppolling();
+    this.removeAllListeners();
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: otel (metrics bridge with OTLP shape)                       */
+/* ------------------------------------------------------------------ */
+
+/** one metric point in the OTLP metrics JSON shape. */
+export interface otlpmetricpoint {
+  readonly name: string;
+  readonly kind: 'counter' | 'gauge' | 'histogram';
+  readonly value: number;
+  readonly attributes?: Readonly<Record<string, string>>;
+}
+
+/**
+ * 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<string, otlpmetricpoint>();
+
+  #key(name: string, attributes?: Record<string, string>): string {
+    return `${name}|${JSON.stringify(attributes ?? {})}`;
+  }
+
+  counter(name: string, delta = 1, attributes?: Record<string, string>): void {
+    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: string, value: number, attributes?: Record<string, string>): void {
+    this.#points.set(this.#key(name, attributes), { name, kind: 'gauge', value, attributes });
+  }
+
+  histogram(name: string, value: number, attributes?: Record<string, string>): void {
+    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(): {
+    resource: { 'service.name': string };
+    scopeMetrics: { scope: { name: string }; metrics: readonly otlpmetricpoint[] };
+  } {
+    return {
+      resource: { 'service.name': 'saddle-scheduler' },
+      scopeMetrics: { scope: { name: 'saddle.scheduler' }, metrics: [...this.#points.values()] },
+    };
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: health (liveness and readiness probes)                      */
+/* ------------------------------------------------------------------ */
+
+/** aggregate health report with per-check durations. */
+export interface healthreport {
+  readonly status: 'pass' | 'fail';
+  readonly checks: readonly { name: string; ok: boolean; durationMs: number }[];
+}
+
+/**
+ * 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<string, { kind: 'liveness' | 'readiness'; fn: () => Promise<void> | void }>();
+
+  register(name: string, kind: 'liveness' | 'readiness', fn: () => Promise<void> | void): this {
+    this.#checks.set(name, { kind, fn });
+    return this;
+  }
+
+  async run(kind: 'liveness' | 'readiness', timeoutMs = 1000): Promise<healthreport> {
+    const checks: { name: string; ok: boolean; durationMs: number }[] = [];
+    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 };
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: shutdown (graceful LIFO coordinator)                        */
+/* ------------------------------------------------------------------ */
+
+/** one shutdown task with its own timeout. */
+export interface shutdowntask {
+  readonly name: string;
+  readonly timeoutMs: number;
+  run(): Promise<void>;
+}
+
+/**
+ * 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: shutdowntask[] = [];
+  #shuttingdown = false;
+
+  add(task: shutdowntask): this {
+    this.#tasks.push(task);
+    return this;
+  }
+
+  /** wires SIGTERM/SIGINT once. */
+  arm(timeoutMs = 10_000): void {
+    const handler = (): void => {
+      void this.shutdown('signal', timeoutMs);
+    };
+    process.once('SIGTERM', handler);
+    process.once('SIGINT', handler);
+  }
+
+  async shutdown(
+    reason: string,
+    timeoutMs = 10_000,
+  ): Promise<{ reason: string; completed: readonly string[]; skipped: readonly string[] }> {
+    this.#shuttingdown = true;
+    const completed: string[] = [];
+    const skipped: string[] = [];
+    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(): boolean {
+    return this.#shuttingdown;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: hooks (typed plugin lifecycle chain)                        */
+/* ------------------------------------------------------------------ */
+
+/** lifecycle events a plugin may observe. */
+export type pluginevent =
+  | 'tenant.create'
+  | 'tenant.admit'
+  | 'allocation.change'
+  | 'spec.reload'
+  | 'scheduler.telemetry';
+
+/** one plugin handler. */
+export type pluginhandler = (payload: unknown) => Promise<void> | void;
+
+/**
+ * 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 implements Disposable {
+  #handlers = new Map<pluginevent, Set<pluginhandler>>();
+
+  on(event: pluginevent, handler: pluginhandler): this {
+    const set = this.#handlers.get(event) ?? new Set<pluginhandler>();
+    set.add(handler);
+    this.#handlers.set(event, set);
+    return this;
+  }
+
+  async emit(event: pluginevent, payload: unknown): Promise<{ handled: number; failed: number }> {
+    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](): void {
+    this.#handlers.clear();
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* context: featureledger (scheduling domain feature index)             */
+/* ------------------------------------------------------------------ */
+
+/** origin of one feature: the v2 future.ts ledger or the v3 additions. */
+export type schedulerfeatureorigin = 'future.ts' | 'omnihypercore-v3';
+
+/** one ledger row: id, origin, name and export name. */
+export interface schedulerfeaturemeta {
+  readonly id: string;
+  readonly origin: schedulerfeatureorigin;
+  readonly name: string;
+  readonly exportname: string;
+}
+
+/**
+ * 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: readonly schedulerfeaturemeta[] = [
+  {
+    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',
+  },
+] satisfies readonly schedulerfeaturemeta[];
+
+/** returns the ledger count split by origin. */
+export function schedulerfeaturecount(): { total: number; absorbed: number; added: number } {
+  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}`,
+} as const satisfies Record<string, string>;
+
+/* ------------------------------------------------------------------ */
+/* context: v5-C feature audit builders (ledger F-053 and F-063 of     */
+/* docs/viability.md appendices A and B)                                */
+/* ------------------------------------------------------------------ */
+
+/** the autoscaling arms the bandit chooses from. */
+export type autoscalearm = 'hold' | 'up1' | 'up2' | 'down1';
+
+/** one observed reward sample and the decision that produced it. */
+export interface autoscalerdecision {
+  readonly arm: autoscalearm;
+  readonly explored: boolean;
+  readonly epsilon: number;
+  readonly expectedreward: number;
+  readonly replicas: number;
+}
+
+/**
+ * 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 {
+  readonly #q = new Map<autoscalearm, { value: number; count: number }>();
+  readonly #arms: readonly autoscalearm[];
+  readonly #floor: number;
+  readonly #decay: number;
+  #epsilon: number;
+  #replicas: number;
+  #lastarm: autoscalearm | undefined;
+
+  constructor(
+    opts: {
+      replicas?: number;
+      minreplicas?: number;
+      maxreplicas?: number;
+      epsilon?: number;
+      epsilonfloor?: number;
+      decay?: number;
+    } = {},
+  ) {
+    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(): number {
+    return this.#replicas;
+  }
+
+  /** current exploration rate (decays toward the floor). */
+  get epsilon(): number {
+    return Number(this.#epsilon.toFixed(4));
+  }
+
+  /** selects the next arm: explore with probability epsilon, else greedy. */
+  decide(targetload: number, observedload: number): autoscalerdecision {
+    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: autoscalearm = 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: number, observedload: number): number {
+    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)}`,
+      );
+    }
+  }
+}
+
+/** one replicated vm.config field: value plus a hybrid logical clock. */
+export interface crdtentry {
+  readonly key: string;
+  readonly value: string;
+  readonly site: string;
+  readonly wallms: number;
+  readonly counter: number;
+}
+
+/** the result of merging a remote document into a local one. */
+export interface crdtmergeresult {
+  readonly applied: number;
+  readonly keptlocal: number;
+  readonly converged: boolean;
+}
+
+/**
+ * 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 {
+  readonly #store = new Map<string, crdtentry>();
+  readonly #site: string;
+  #lastms = 0;
+  #counter = 0;
+
+  constructor(site: string) {
+    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(): string {
+    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: string, value: string): crdtentry {
+    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: crdtentry = {
+        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: string): crdtentry | undefined {
+    return this.#store.get(key);
+  }
+
+  /** the full delta set a remote peer needs (all entries). */
+  snapshot(): readonly crdtentry[] {
+    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: readonly crdtentry[], remotesite?: vmconfigcrdt): crdtmergeresult {
+    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(): Record<string, string> {
+    const doc: Record<string, string> = {};
+    for (const [key, entry] of this.#store) doc[key] = entry.value;
+    return doc;
+  }
+
+  #samekeys(other: vmconfigcrdt): boolean {
+    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: crdtentry, incumbent: crdtentry): boolean {
+  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;
+}