@soulcraft/cor 3.0.0-rc.1

package/dist/resource/OsMemoryProbe.js

@@ -0,0 +1,206 @@
+/**
+ * @module resource/OsMemoryProbe
+ * @description OS-level memory observer for the cor 3.0 **Adaptive
+ * DiskANN** mode selector (Piece J of the cor 3.0 plan).
+ *
+ * The {@link ResourceManager} already observes the V8 heap and a
+ * coarse system-RSS pressure ratio (Piece 8). What it didn't have
+ * was a read on the kernel's `MemAvailable` figure — the metric the
+ * Linux kernel computes as "how much physical RAM can a new
+ * allocation claim without swapping," factoring in reclaimable page
+ * cache and slab. That's the right signal for the adaptive selector
+ * to pick a DiskANN open mode in multi-tenant scenarios where a
+ * shared box runs many brainy+cor instances: each instance's
+ * `os.freemem()` undercounts available memory (it reports MemFree,
+ * not MemAvailable), so a naïve `freemem`-based check would push
+ * the selector toward OnDisk hints even when there's plenty of
+ * reclaimable cache available.
+ *
+ * ## Surface
+ *
+ * - {@link parseMeminfo} — pure parser; fixture-friendly.
+ * - {@link OsMemoryProbe} — readers + caching wrapper. Dependency-
+ *   injected so tests can simulate Linux on macOS and exercise the
+ *   `MemAvailable` missing branch without touching the real
+ *   `/proc/meminfo`.
+ *
+ * ## Why a cache
+ *
+ * `/proc/meminfo` reads cost ~10 μs of syscall time — not free, but
+ * also not worth re-reading on every single call. The 250 ms cache
+ * is comfortably below the 5 s pressure-tick cadence and the 30 s
+ * rebalance cadence the ResourceManager already runs, so any
+ * meaningful pressure event lands on a fresh read.
+ *
+ * ## Non-Linux fallback
+ *
+ * On macOS and Windows there is no `/proc/meminfo`. The probe falls
+ * back to `os.totalmem()` + `os.freemem()` and marks the snapshot
+ * `source: 'os-fallback'` so callers can degrade gracefully (the
+ * adaptive selector currently treats fallback snapshots as
+ * "available bytes is conservative, prefer Hybrid over OnDisk").
+ */
+import os from 'node:os';
+import { readFileSync } from 'node:fs';
+const KIB = 1024;
+/**
+ * Match a `Field:    value [kB]` line in `/proc/meminfo`.
+ *
+ * Allowed key chars cover the punctuation that real kernel-side
+ * names use: `Active(anon)`, `Inactive(file)`, etc. We don't read
+ * those fields ourselves, but the regex tolerates them so a typo in
+ * a future key extension doesn't silently fall through.
+ */
+const FIELD_PATTERN = /^([A-Za-z()_]+):\s+(\d+)(?:\s+kB)?\s*$/;
+/**
+ * Parse a `/proc/meminfo` text blob and extract the three fields the
+ * probe needs. Pure function — no I/O, fully deterministic, the
+ * only thing fixture tests need to cover.
+ *
+ * Returns `null` only when `MemTotal` is missing, which would mean
+ * the input isn't `/proc/meminfo` at all (every Linux kernel since
+ * the file existed has emitted it). Missing `MemAvailable` or
+ * `MemFree` is normal on old or specialised kernels and is left for
+ * the snapshot composer to handle.
+ */
+export function parseMeminfo(text) {
+    const fields = {};
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trimEnd();
+        if (line.length === 0)
+            continue;
+        const match = line.match(FIELD_PATTERN);
+        if (!match)
+            continue;
+        const key = match[1];
+        const value = parseInt(match[2], 10);
+        if (!Number.isFinite(value) || value < 0)
+            continue;
+        if (key === 'MemTotal')
+            fields.totalKib = value;
+        else if (key === 'MemAvailable')
+            fields.availableKib = value;
+        else if (key === 'MemFree')
+            fields.freeKib = value;
+    }
+    if (fields.totalKib === undefined)
+        return null;
+    return fields;
+}
+function clamp01(x) {
+    if (!Number.isFinite(x))
+        return 0;
+    if (x < 0)
+        return 0;
+    if (x > 1)
+        return 1;
+    return x;
+}
+/**
+ * Build an {@link OsMemorySnapshot} from the parsed `/proc/meminfo`
+ * fields. Visible for tests; production callers use
+ * {@link OsMemoryProbe.snapshot}.
+ */
+export function snapshotFromMeminfo(fields) {
+    const totalBytes = (fields.totalKib ?? 0) * KIB;
+    const freeBytes = (fields.freeKib ?? 0) * KIB;
+    // MemAvailable landed in Linux 3.14. Older kernels need the
+    // MemFree fallback — strictly worse signal but the best we have.
+    const availableBytes = fields.availableKib !== undefined ? fields.availableKib * KIB : freeBytes;
+    const pressureScore = totalBytes > 0 ? clamp01(1 - availableBytes / totalBytes) : 0;
+    return {
+        totalBytes,
+        availableBytes,
+        freeBytes,
+        pressureScore,
+        source: 'proc-meminfo',
+    };
+}
+/**
+ * Build the os-fallback snapshot from Node's `os` module. Visible
+ * for tests; production callers use {@link OsMemoryProbe.snapshot}.
+ */
+export function snapshotFromOs() {
+    const totalBytes = os.totalmem();
+    const freeBytes = os.freemem();
+    // No MemAvailable equivalent without a platform-specific syscall;
+    // freemem is the best approximation available cross-platform.
+    const pressureScore = totalBytes > 0 ? clamp01(1 - freeBytes / totalBytes) : 0;
+    return {
+        totalBytes,
+        availableBytes: freeBytes,
+        freeBytes,
+        pressureScore,
+        source: 'os-fallback',
+    };
+}
+/**
+ * Default `/proc/meminfo` reader. Returns the file's text or `null`
+ * when the file doesn't exist / is unreadable (the expected case on
+ * macOS and Windows). Synchronous because the file is virtual and
+ * reads cost microseconds.
+ */
+function defaultProcReader() {
+    try {
+        return readFileSync('/proc/meminfo', 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cached `/proc/meminfo` observer. Wire one instance into the
+ * {@link ResourceManager}; the adaptive DiskANN selector (Piece I)
+ * will read `snapshot()` at brain-open time.
+ */
+export class OsMemoryProbe {
+    cacheMs;
+    procReader;
+    osFallback;
+    now;
+    cached = null;
+    constructor(options = {}) {
+        this.cacheMs = options.cacheMs ?? 250;
+        this.procReader = options.procReader ?? defaultProcReader;
+        this.osFallback = options.osFallback ?? snapshotFromOs;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Latest memory snapshot. Cached for {@link OsMemoryProbeOptions.cacheMs}
+     * milliseconds; calls inside the window reuse the cached value.
+     */
+    snapshot() {
+        const now = this.now();
+        if (this.cached && this.cached.expires > now) {
+            return this.cached.snapshot;
+        }
+        const text = this.procReader();
+        let fresh;
+        if (text !== null) {
+            const fields = parseMeminfo(text);
+            if (fields !== null) {
+                fresh = snapshotFromMeminfo(fields);
+            }
+            else {
+                // The proc reader succeeded but the parse failed — malformed
+                // file. Degrade rather than throw so a flaky kernel doesn't
+                // crash the whole observation surface.
+                fresh = this.osFallback();
+            }
+        }
+        else {
+            fresh = this.osFallback();
+        }
+        this.cached = { snapshot: fresh, expires: now + this.cacheMs };
+        return fresh;
+    }
+    /**
+     * Invalidate the cache so the next {@link snapshot} call performs
+     * a fresh read. Used by tests; production callers shouldn't need
+     * this because the cache TTL is short.
+     */
+    invalidate() {
+        this.cached = null;
+    }
+}
+//# sourceMappingURL=OsMemoryProbe.js.map

package/dist/resource/ResourceManager.d.ts

@@ -0,0 +1,491 @@
+/**
+ * @module resource/ResourceManager
+ * @description Adaptive resource manager for multi-instance Brainy deployments.
+ *
+ * Observes system resources (RAM, CPU, cgroups limits, active instance count)
+ * and dynamically adjusts cache sizing and memory budgets. All products
+ * (Workshop, Venue, Academy) benefit automatically — zero configuration needed.
+ *
+ * Singleton — one ResourceManager per Node.js process, shared across all
+ * Brainy instances. Registered as a Cor provider so SDK and brainy can
+ * query resource profiles without importing cor directly.
+ *
+ * ## Per-category memory budget (Piece 8 extension, cor 3.0)
+ *
+ * The cache budget is split across four named categories — `vectors`,
+ * `metadata`, `embedding`, `other` — each with a hardcoded base share of
+ * the total cache pool (50% / 25% / 15% / 10% respectively). Subsystems
+ * (cor's native LSM metadata index, DiskANN graph, embedding cache, etc.)
+ * register as `MemoryBudgetSubscriber`s with their category and a callback
+ * that fires whenever their effective allocation changes.
+ *
+ * Per the zero-config principle: the base shares are the **starting point**,
+ * not a hard cap. The ResourceManager observes actual utilization
+ * (`reportNativeMemory(name, bytes)` calls) on a 5-second pressure-tick
+ * cadence and **dynamically rebalances** allocations at runtime —
+ * under-utilized categories donate capacity to over-utilized ones,
+ * bounded so no category can shrink below 25% of its base share or grow
+ * above 200% of its base share. Operators never tune the split; the
+ * system adapts to its workload.
+ *
+ * The pre-existing `setCacheResizeCallback` API is preserved as a
+ * back-compat shim that auto-subscribes to the `other` category with a
+ * zero-bytes report — no behavior change for existing wiring.
+ *
+ * ## OS-memory observation (Piece J, cor 3.0)
+ *
+ * A built-in {@link OsMemoryProbe} reads `/proc/meminfo` on Linux
+ * (with an `os.totalmem`/`os.freemem` fallback elsewhere) and
+ * exposes the result via {@link getResourceProfile}'s `osMemory`
+ * field and the convenience accessor
+ * {@link ResourceManager.getOsMemorySnapshot}. The **Adaptive
+ * DiskANN** mode selector (Piece I) reads this snapshot at
+ * brain-open time to pick between in-memory / hybrid / on-disk
+ * operating modes — the key signal is `availableBytes`
+ * (`MemAvailable` on Linux), which counts reclaimable page cache
+ * as "available for new allocations." Naïve `os.freemem()`
+ * undercounts in multi-tenant scenarios where many brainy+cor
+ * instances share a box.
+ */
+import { OsMemoryProbe, type OsMemorySnapshot } from './OsMemoryProbe.js';
+/**
+ * Snapshot of system resources and computed recommendations.
+ */
+export interface ResourceProfile {
+    /** Total system memory in bytes */
+    totalMemory: number;
+    /** Free system memory in bytes (at observation time) */
+    freeMemory: number;
+    /** Effective memory limit (cgroups-aware: min of system and cgroup limit) */
+    effectiveLimit: number;
+    /** Whether running in a container (cgroups detected) */
+    isContainer: boolean;
+    /** Process RSS in bytes */
+    processRss: number;
+    /** Process heap used in bytes */
+    heapUsed: number;
+    /** Number of CPU cores */
+    cpuCount: number;
+    /** Number of active brainy instances tracked */
+    activeInstances: number;
+    /** Total entities across all active instances */
+    totalEntities: number;
+    /** Recommended cache budget in bytes */
+    recommendedCacheSize: number;
+    /** Memory pressure level */
+    pressure: 'normal' | 'elevated' | 'critical';
+    /** Per-instance average memory estimate in bytes */
+    avgInstanceMemory: number;
+    /** Estimated headroom for new instances in bytes */
+    headroom: number;
+    /**
+     * **Piece 8 — V8 heap tracking.** Brainy's TS-side memory pressure
+     * is a separate signal from system RSS pressure: the V8 heap has its
+     * own hard ceiling (controlled by `--max-old-space-size`, default
+     * ~4 GB on Node) and GC starts thrashing well before the system is
+     * out of RAM. Tracked so subsystems (filter lowering, iter-spill,
+     * VFS pool) can shed JS allocations when the heap fills even if
+     * system memory is plentiful.
+     */
+    v8Heap: V8HeapSnapshot;
+    /**
+     * **Piece J — OS-memory observation.** Snapshot of the
+     * kernel-reported `MemTotal` / `MemAvailable` / `MemFree` (Linux)
+     * or `os.totalmem` / `os.freemem` (fallback). Distinct from
+     * {@link processRss} (which is the THIS process's footprint) and
+     * from {@link freeMemory} (which is the legacy `os.freemem()`
+     * reading). The Adaptive DiskANN mode selector (Piece I) reads
+     * `osMemory.availableBytes` to decide which open mode to apply.
+     */
+    osMemory: OsMemorySnapshot;
+}
+/**
+ * Snapshot of V8 heap state at observation time. Mirrors the subset
+ * of `v8.getHeapStatistics()` that matters for budget decisions, plus
+ * the derived pressure classification.
+ */
+export interface V8HeapSnapshot {
+    /** `used_heap_size` — live JS object footprint */
+    usedHeapSize: number;
+    /** `heap_size_limit` — V8's hard ceiling before OOM */
+    heapSizeLimit: number;
+    /** `external_memory` — buffers + mmap'd regions outside the JS heap */
+    externalMemory: number;
+    /** `used_heap_size / heap_size_limit` (0..1) */
+    ratio: number;
+    /**
+     * Pressure classification — same three-level shape as the
+     * system-RSS `pressure` field for consistency. Thresholds chosen
+     * to fire BEFORE V8's GC starts thrashing:
+     * - `elevated` ≥ 0.75 ratio (matches system PRESSURE_ELEVATED)
+     * - `critical` ≥ 0.90 ratio (matches system PRESSURE_CRITICAL)
+     *
+     * Subsystems should treat `elevated` as "stop growing
+     * allocations, prefer iter-spill paths" and `critical` as "shed
+     * allocations now, before the next minor GC".
+     */
+    pressure: 'normal' | 'elevated' | 'critical';
+}
+export type { OsMemorySnapshot } from './OsMemoryProbe.js';
+/**
+ * The named memory categories that share the cache budget. Subsystems
+ * register against one of these so the ResourceManager can rebalance
+ * allocations between them based on observed pressure.
+ */
+export type MemoryCategory = 'vectors' | 'metadata' | 'embedding' | 'other';
+/**
+ * Callback fired when a subscriber's effective allocation changes. The
+ * `allowedBytes` value is the **current** ceiling — subsystems should
+ * cap their resident bytes at this number; if they're currently over,
+ * they should start shedding (evict, flush, etc).
+ */
+export type MemoryBudgetCallback = (allowedBytes: number) => void;
+/**
+ * Adaptive resource manager for multi-instance Brainy deployments.
+ *
+ * Tracks active brainy instances, observes system resources, and computes
+ * dynamic memory budgets for cache sizing and pool eviction.
+ *
+ * @example
+ * ```typescript
+ * const rm = ResourceManager.getInstance()
+ * rm.trackInstance('tenant-wicks', 450)
+ *
+ * const profile = rm.getResourceProfile()
+ * console.log(`Cache budget: ${profile.recommendedCacheSize / 1024 / 1024}MB`)
+ * console.log(`Headroom for new instances: ${profile.headroom / 1024 / 1024}MB`)
+ * ```
+ */
+export declare class ResourceManager {
+    private static instance;
+    private readonly instances;
+    private readonly effectiveLimit;
+    private readonly isContainer;
+    private rebalanceTimer;
+    private onCacheResize;
+    /**
+     * **Piece J — OS-memory observation.** `/proc/meminfo`-backed
+     * snapshot source. Held as an instance field so tests can swap
+     * the probe via {@link _testInjectOsMemoryProbe}.
+     */
+    private osMemoryProbe;
+    /**
+     * Active per-category memory subscribers, keyed by name. Each
+     * subscriber receives notifications when its effective allocation
+     * changes (whether from a whole-pool rebalance or a category-level
+     * dynamic adaptation).
+     */
+    private readonly subscribers;
+    /**
+     * Current dynamic share for each category. Starts at `BASE_CATEGORY_SHARES`
+     * and adapts at runtime to reported pressure. Sum across categories is
+     * preserved at exactly 1.0 by the rebalance algorithm.
+     */
+    private categoryShares;
+    /**
+     * 5-second pressure-tick timer. Only running while at least one
+     * category is at or above the high-water threshold; auto-stops once
+     * every category falls back below the low-water threshold.
+     */
+    private pressureTickTimer;
+    /**
+     * Tracks how many consecutive ticks have shown no pressure — used to
+     * decide when to stop the pressure-tick.
+     */
+    private quietTicks;
+    /** One-shot guard for the multi-tenant OS-limits deployment warning. */
+    private osLimitsWarned;
+    private constructor();
+    /**
+     * Get the singleton ResourceManager instance.
+     */
+    static getInstance(): ResourceManager;
+    /**
+     * **Back-compat callback** for the cortex 2.x cache resize wiring.
+     * The cor plugin (`src/plugin.ts`) registers brainy's
+     * `UnifiedCache.setMaxSize` via this method; the callback fires on
+     * every whole-pool rebalance with the TOTAL cache budget (not a
+     * per-category slice).
+     *
+     * Behavior is unchanged from cortex 2.x: the callback receives the
+     * full `recommendedCacheSize` from `getResourceProfile()` whenever
+     * the pool resizes. The new per-category subscriber API
+     * ([`registerMemoryBudgetSubscriber`](#registerMemoryBudgetSubscriber))
+     * runs in PARALLEL — they don't interfere. Legacy callers can keep
+     * their existing wiring; new code that wants a category-specific
+     * allocation registers as a subscriber.
+     *
+     * @param callback - Called with the new recommended cache size in bytes
+     */
+    setCacheResizeCallback(callback: (newSize: number) => void): void;
+    /**
+     * Register a subscriber for per-category memory budget notifications.
+     *
+     * Subscribers receive an `allowedBytes` value whenever their effective
+     * allocation changes — either because the overall pool resized (system
+     * memory shift, instance count change) or because the dynamic
+     * rebalance loop shifted capacity between categories under observed
+     * pressure.
+     *
+     * The returned function deregisters the subscriber. Each `name` must
+     * be unique; registering twice with the same name replaces the prior
+     * registration.
+     *
+     * @param name - Unique subscriber name (used with `reportNativeMemory`)
+     * @param category - The category this subscriber draws from
+     * @param callback - Invoked with the current `allowedBytes` ceiling
+     * @returns A deregistration function (call to detach the subscriber)
+     *
+     * @example
+     * ```typescript
+     * const rm = ResourceManager.getInstance()
+     * const unsubscribe = rm.registerMemoryBudgetSubscriber(
+     *   'metadata-lsm',
+     *   'metadata',
+     *   (allowed) => { lsm.setMaxBytes(allowed) }
+     * )
+     * // Later, when the LSM measures its footprint:
+     * rm.reportNativeMemory('metadata-lsm', lsm.currentBytes())
+     * // To detach:
+     * unsubscribe()
+     * ```
+     */
+    registerMemoryBudgetSubscriber(name: string, category: MemoryCategory, callback: MemoryBudgetCallback): () => void;
+    /**
+     * Report the current resident-memory footprint of a registered
+     * subscriber, in bytes. The rebalance loop uses these values to
+     * detect category-level pressure and shift capacity dynamically.
+     *
+     * Call this whenever the subscriber's footprint changes meaningfully
+     * (after a flush, after a major allocation, etc). The pressure-tick
+     * fires within 5 seconds of any single category exceeding 90% of its
+     * current allocation; calling more often is harmless.
+     *
+     * Unknown names are silently dropped — a subscriber that has
+     * deregistered may still have pending reports in flight.
+     */
+    reportNativeMemory(name: string, bytes: number): void;
+    /**
+     * Report the current dynamic share for each category. Mostly used by
+     * tests + the diagnostics surface; production callers should subscribe
+     * via [`registerMemoryBudgetSubscriber`] instead of polling.
+     *
+     * The sum across categories is always exactly 1.0 (modulo float
+     * rounding); allocations sum to the cache budget.
+     */
+    getCategoryShares(): Readonly<Record<MemoryCategory, number>>;
+    /**
+     * The current per-category allowed-bytes ceiling. Same as what an
+     * active subscriber received in its last callback. Provided for
+     * diagnostics; production callers subscribe instead of polling.
+     */
+    getCategoryAllowedBytes(category: MemoryCategory): number;
+    /**
+     * Start periodic rebalancing (every 30s). Aligns with brainy's existing
+     * memory pressure monitoring interval.
+     */
+    startRebalancing(): void;
+    /**
+     * Stop periodic rebalancing.
+     */
+    stopRebalancing(): void;
+    /**
+     * Start the 5-second pressure-tick if it isn't already running.
+     * Idempotent. Called from `reportNativeMemory` when a category crosses
+     * the high-water threshold; stops on its own when every category
+     * falls back below the low-water threshold for 3 consecutive ticks.
+     */
+    private ensurePressureTickRunning;
+    private stopPressureTick;
+    /**
+     * Test-only hook to drive a pressure tick synchronously without
+     * waiting for the timer. Not exposed to production callers; tests
+     * use this to assert the rebalance behaviour deterministically.
+     * @internal
+     */
+    _testTickPressure(): void;
+    /**
+     * Track a new or updated brainy instance. Call when a brainy instance is
+     * created or when its entity count changes significantly.
+     *
+     * @param key - Unique scope key for this instance (e.g. tenant slug, user:workspace)
+     * @param entityCount - Current entity count in this instance
+     */
+    trackInstance(key: string, entityCount: number): void;
+    /**
+     * One-shot deployment warning: when enough brains are pooled in ONE
+     * process that OS file/map limits could bottleneck before RAM — and the
+     * limits are below the projected need — log the exact fix. Cor
+     * auto-raises the SOFT `nofile` limit itself; the hard cap +
+     * `vm.max_map_count` must be set by the deployment (a process cannot
+     * raise those). Context-aware: silent for a single big brain (Venue);
+     * fires only at real pool scale. See `docs/ADR-004-multi-tenant-storage.md`.
+     */
+    private maybeWarnOsLimits;
+    /**
+     * Stop tracking a brainy instance. Call when the instance is evicted or closed.
+     *
+     * @param key - The scope key that was passed to trackInstance()
+     */
+    untrackInstance(key: string): void;
+    /**
+     * Record an access to an instance (updates lastAccess for weighted eviction).
+     *
+     * @param key - The scope key
+     */
+    touchInstance(key: string): void;
+    /**
+     * **Piece 8 — V8 heap tracking.** Snapshot the current V8 heap
+     * state and classify pressure. Cheap call (a single
+     * `v8.getHeapStatistics()` syscall + a few divisions); fine to
+     * invoke per-query on the hot path. Subsystems like brainy's filter
+     * lowering use this to early-exit before allocating big
+     * intermediate bitmaps that would push the heap over the ceiling.
+     *
+     * The pressure classification uses the same three-level shape as
+     * system-RSS pressure (`normal` / `elevated` / `critical`) so
+     * subscribers can branch uniformly.
+     */
+    getHeapStats(): V8HeapSnapshot;
+    /**
+     * **Piece 8.** Convenience accessor returning just the heap
+     * pressure classification — cheaper than constructing a full
+     * {@link V8HeapSnapshot} when the caller only needs the branch.
+     */
+    getHeapPressure(): 'normal' | 'elevated' | 'critical';
+    /**
+     * **Piece J.** Latest OS-memory snapshot from `/proc/meminfo`
+     * (Linux) or the os-fallback path. Cached for 250 ms by the
+     * underlying {@link OsMemoryProbe}; consecutive calls inside the
+     * cache window reuse the value. Cheaper than
+     * {@link getResourceProfile} when the caller only needs the
+     * memory snapshot (the Adaptive DiskANN selector — Piece I — is
+     * the canonical caller).
+     */
+    getOsMemorySnapshot(): OsMemorySnapshot;
+    /**
+     * Test-only hook to swap the OS-memory probe with a deterministic
+     * stand-in. Production code must not call this — the singleton's
+     * probe is part of the resource-observation contract.
+     * @internal
+     */
+    _testInjectOsMemoryProbe(probe: OsMemoryProbe): void;
+    /**
+     * Compute a full resource profile snapshot.
+     *
+     * @returns Current system resources, instance stats, and recommendations
+     */
+    getResourceProfile(): ResourceProfile;
+    /**
+     * Check if there's enough memory headroom to create a new instance
+     * with the given entity count.
+     *
+     * @param estimatedEntities - Expected entity count for the new instance
+     * @returns true if headroom is sufficient
+     */
+    canAccommodateInstance(estimatedEntities?: number): boolean;
+    /**
+     * **Piece 8 commit 2 — observed per-entity RAM estimate.** When
+     * any subscriber has reported native memory via
+     * {@link reportNativeMemory}, the ratio of total reported bytes
+     * to total tracked entities is the actual observed per-entity
+     * footprint — accurate for THIS deployment's workload mix instead
+     * of a one-size-fits-all guess. Falls back to
+     * {@link FALLBACK_BYTES_PER_ENTITY} when subscribers haven't
+     * reported (cold boot, no instances tracked, or workloads where
+     * the brain hasn't done any reading yet).
+     *
+     * Floored at {@link MIN_BYTES_PER_ENTITY} so a subscriber that
+     * temporarily under-reports during a flush doesn't make
+     * `canAccommodateInstance` say "yes" to instances that can't fit.
+     *
+     * Cheap call: O(subscribers + instances) — both bounded by a few
+     * dozen in production. Fine to invoke per trackInstance /
+     * canAccommodateInstance call.
+     */
+    private observedBytesPerEntity;
+    /**
+     * Get the scope key of the instance that should be evicted first.
+     * Uses weighted scoring: large + idle instances are evicted before
+     * small + active ones.
+     *
+     * @returns The key to evict, or null if no instances are tracked
+     */
+    getEvictionCandidate(): string | null;
+    /**
+     * Rebalance cache sizing based on current instance count and memory state.
+     *
+     * Three responsibilities:
+     *   1. Recompute the total cache budget from instance count + system
+     *      memory (the pre-Piece-8 behaviour).
+     *   2. Fire the back-compat `onCacheResize` if it exists.
+     *   3. Notify every per-category subscriber of its current
+     *      `allowedBytes` ceiling — picks up any whole-pool shift even
+     *      when the per-category dynamic adaptation isn't pressed.
+     */
+    private rebalance;
+    /**
+     * Drive one tick of the per-category dynamic rebalance. Reads the
+     * latest `reportNativeMemory` values, identifies over- and under-
+     * utilized categories, shifts the dynamic shares between them
+     * (bounded by `CATEGORY_MIN_SHARE` / `CATEGORY_MAX_SHARE`), and
+     * notifies any subscriber whose allowance changed meaningfully.
+     *
+     * Auto-stops the pressure-tick loop after 3 consecutive quiet ticks
+     * (no category > low-water).
+     */
+    private runPressureTick;
+    /**
+     * Shift dynamic share from donor categories to recipient categories.
+     *
+     * Both sides are PRE-CAPPED by the per-category min/max share bounds
+     * (25% / 200% of base share, respectively) BEFORE the proportional
+     * distribution runs. Pre-capping is the only safe pattern: clamping
+     * after a proportional split would either (a) lose capacity (donors
+     * give shares that recipients can't accept due to their ceiling) or
+     * (b) require renormalization, which silently violates the ceiling.
+     *
+     * `transfer = min(total bounded contribution, total bounded demand)`
+     * — by construction the per-donor `give` and per-recipient `take`
+     * sums are equal, so the shares always sum to 1.0 without
+     * renormalization. The float drift over many cycles is bounded by
+     * the floating-point precision of a single division, well under any
+     * test's threshold.
+     */
+    private rebalanceShares;
+    /**
+     * Compute the current allowed-bytes ceiling for a category.
+     */
+    private computeAllowedBytes;
+    /**
+     * Sum the reportedBytes of every subscriber by category.
+     */
+    private aggregateReportedBytesByCategory;
+    /**
+     * Notify every subscriber of its current allowed-bytes ceiling. Fires
+     * the callback only when the allowance has shifted by more than the
+     * `NOTIFY_DELTA` threshold from the last delivered value — avoids
+     * spurious wakeups on small re-rebalances.
+     */
+    private notifySubscribers;
+    /**
+     * Normalize categoryShares so they sum to exactly 1.0. Compensates for
+     * float drift over many rebalance cycles. Preserves the relative
+     * proportions of the four categories.
+     */
+    private renormalizeShares;
+    /**
+     * Compute the recommended cache budget given current instance memory usage.
+     *
+     * Formula: min(MAX_CACHE_RATIO × available, available - fixed - instances - headroom)
+     * Clamped to MIN_CACHE_BYTES.
+     */
+    private computeCacheBudget;
+    /**
+     * Determine memory pressure level from current RSS.
+     */
+    private computePressure;
+    private getTotalEntities;
+    private getTotalInstanceMemory;
+}
+//# sourceMappingURL=ResourceManager.d.ts.map