@soulcraft/cor 3.0.0-rc.1

package/dist/resource/ResourceManager.js

@@ -0,0 +1,960 @@
+/**
+ * @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 os from 'node:os';
+import v8 from 'node:v8';
+import { readFileSync, existsSync } from 'node:fs';
+import { OsMemoryProbe, } from './OsMemoryProbe.js';
+import { prodLog } from '@soulcraft/brainy/internals';
+import { getOpenFileLimitInfo } from '../native/index.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Fixed process overhead: embedding model (88MB) + Node.js baseline (~150MB) */
+const FIXED_OVERHEAD_BYTES = 240 * 1024 * 1024;
+/**
+ * **Piece 8 commit 2 — fallback per-entity RAM estimate.** Used by
+ * `trackInstance` + `canAccommodateInstance` ONLY when no subscriber
+ * has reported native memory yet (cold-boot, no instances active).
+ * Once any subscriber reports nativeMemoryBytes, the observed
+ * `totalReportedBytes / totalEntities` ratio takes precedence — see
+ * {@link ResourceManager.observedBytesPerEntity}.
+ *
+ * The pre-Piece-8 constant was `1024` bytes/entity, which over-
+ * estimated the RAM working set by ~300× at the cor 3.0 10B
+ * design target (32 GB / 10B entities = ~3.2 bytes/entity for
+ * everything that's actually resident). The new fallback of 256
+ * bytes is still conservative — accurate for sub-million-entity
+ * brains where most state is RAM-resident, intentionally over-
+ * estimating for billion-scale so the admission gate errs toward
+ * "don't admit a new instance" until real reports correct the
+ * estimate.
+ */
+const FALLBACK_BYTES_PER_ENTITY = 256;
+/**
+ * Floor for the observed-bytes-per-entity calculation. Prevents an
+ * absurdly-low estimate (e.g., a subscriber temporarily reporting
+ * zero bytes while a flush is in progress) from making
+ * `canAccommodateInstance` say "yes" to instances that can't
+ * possibly fit. 4 bytes is the per-entity u32 ID alone; any real
+ * deployment carries more state than that.
+ */
+const MIN_BYTES_PER_ENTITY = 4;
+/** Per-instance baseline overhead before entities */
+const INSTANCE_BASELINE_BYTES = 4 * 1024 * 1024;
+/** Minimum cache size — never shrink below this */
+const MIN_CACHE_BYTES = 128 * 1024 * 1024;
+/** Maximum fraction of available RAM for cache when instances are present */
+const MAX_CACHE_RATIO = 0.35;
+/** Memory pressure thresholds (fraction of effective limit) */
+const PRESSURE_ELEVATED = 0.75;
+const PRESSURE_CRITICAL = 0.90;
+/**
+ * V8 heap pressure thresholds (fraction of `heap_size_limit`).
+ * Matched to the system-RSS thresholds for consistency; the V8 GC
+ * starts thrashing around 0.90 ratio so we want to fire `critical`
+ * before subsystems run out of allocation headroom.
+ */
+const V8_HEAP_PRESSURE_ELEVATED = 0.75;
+const V8_HEAP_PRESSURE_CRITICAL = 0.90;
+/** Rebalance interval in milliseconds */
+const REBALANCE_INTERVAL_MS = 30_000;
+/**
+ * Hardcoded base shares of the cache budget per category. These are the
+ * starting point — the ResourceManager dynamically rebalances at runtime
+ * based on observed pressure. NEVER expose these as a tuning knob: the
+ * [[zero-config-dynamic-adaptation]] principle says configuration is the
+ * last escape hatch, not the first. If a workload genuinely needs a
+ * different split, the adaptation loop figures it out from the reported
+ * bytes.
+ */
+const BASE_CATEGORY_SHARES = {
+    vectors: 0.5,
+    metadata: 0.25,
+    embedding: 0.15,
+    other: 0.1,
+};
+/**
+ * Pressure-tick cadence — 5 seconds. The pressure-tick only fires when
+ * SOME category is at >90% of its current allocation; it stops on its
+ * own when every category drops back under 70%. The 30s rebalance
+ * remains the always-on cadence for whole-pool sizing changes (instance
+ * count, system memory shifts).
+ */
+const PRESSURE_TICK_INTERVAL_MS = 5_000;
+/**
+ * Per-category pressure thresholds used by the pressure-tick.
+ */
+const CATEGORY_PRESSURE_HIGH = 0.9;
+const CATEGORY_PRESSURE_LOW = 0.7;
+/**
+ * Per-category bounds on dynamic rebalancing. A category can shrink to
+ * 25% of its base allocation (giving the rest to others) or grow to
+ * 200% of its base allocation (consuming surplus from underutilized
+ * categories). Outside these bounds the system stops adapting in that
+ * direction — protecting against pathological workloads that would
+ * starve a small category entirely.
+ */
+const CATEGORY_MIN_SHARE = 0.25;
+const CATEGORY_MAX_SHARE = 2.0;
+/**
+ * Minimum change in allowed bytes before notifying a subscriber. Avoids
+ * spurious callbacks when the rebalance only nudges allocations by a
+ * few KB. 5% relative + 1 MB absolute.
+ */
+const NOTIFY_DELTA_RATIO = 0.05;
+const NOTIFY_DELTA_BYTES = 1024 * 1024;
+// ---------------------------------------------------------------------------
+// Cgroup detection (reuses brainy's approach)
+// ---------------------------------------------------------------------------
+/**
+ * Detect container memory limit from cgroups v1 or v2.
+ *
+ * @returns Memory limit in bytes, or null if not in a container / unlimited
+ */
+function detectCgroupLimit() {
+    try {
+        // cgroups v2
+        const v2Path = '/sys/fs/cgroup/memory.max';
+        if (existsSync(v2Path)) {
+            const content = readFileSync(v2Path, 'utf8').trim();
+            if (content !== 'max') {
+                const bytes = parseInt(content, 10);
+                if (bytes > 64 * 1024 * 1024 && bytes < 1024 * 1024 * 1024 * 1024) {
+                    return bytes;
+                }
+            }
+        }
+        // cgroups v1
+        const v1Path = '/sys/fs/cgroup/memory/memory.limit_in_bytes';
+        if (existsSync(v1Path)) {
+            const content = readFileSync(v1Path, 'utf8').trim();
+            const bytes = parseInt(content, 10);
+            if (bytes > 64 * 1024 * 1024 && bytes < os.totalmem() * 2) {
+                return bytes;
+            }
+        }
+    }
+    catch {
+        // Not in a cgroup environment
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// ResourceManager
+// ---------------------------------------------------------------------------
+/**
+ * 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 class ResourceManager {
+    static instance = null;
+    instances = new Map();
+    effectiveLimit;
+    isContainer;
+    rebalanceTimer = null;
+    onCacheResize = null;
+    /**
+     * **Piece J — OS-memory observation.** `/proc/meminfo`-backed
+     * snapshot source. Held as an instance field so tests can swap
+     * the probe via {@link _testInjectOsMemoryProbe}.
+     */
+    osMemoryProbe = new 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).
+     */
+    subscribers = new Map();
+    /**
+     * 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.
+     */
+    categoryShares = { ...BASE_CATEGORY_SHARES };
+    /**
+     * 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.
+     */
+    pressureTickTimer = null;
+    /**
+     * Tracks how many consecutive ticks have shown no pressure — used to
+     * decide when to stop the pressure-tick.
+     */
+    quietTicks = 0;
+    /** One-shot guard for the multi-tenant OS-limits deployment warning. */
+    osLimitsWarned = false;
+    constructor() {
+        const cgroupLimit = detectCgroupLimit();
+        const systemTotal = os.totalmem();
+        this.isContainer = cgroupLimit !== null;
+        this.effectiveLimit = cgroupLimit !== null
+            ? Math.min(cgroupLimit, systemTotal)
+            : systemTotal;
+    }
+    /**
+     * Get the singleton ResourceManager instance.
+     */
+    static getInstance() {
+        if (!ResourceManager.instance) {
+            ResourceManager.instance = new ResourceManager();
+        }
+        return ResourceManager.instance;
+    }
+    /**
+     * **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) {
+        this.onCacheResize = callback;
+    }
+    /**
+     * 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, category, callback) {
+        const subscriber = {
+            name,
+            category,
+            callback,
+            reportedBytes: 0,
+            lastAllowed: 0,
+        };
+        this.subscribers.set(name, subscriber);
+        // Fire the initial allowed-bytes value so the subscriber knows its
+        // starting ceiling without having to call getResourceProfile() first.
+        const initial = this.computeAllowedBytes(category);
+        subscriber.lastAllowed = initial;
+        try {
+            callback(initial);
+        }
+        catch {
+            // Subscriber callback threw; swallow — we don't trust foreign
+            // callbacks to bring down the rebalance loop.
+        }
+        return () => {
+            const current = this.subscribers.get(name);
+            if (current === subscriber) {
+                this.subscribers.delete(name);
+            }
+        };
+    }
+    /**
+     * 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, bytes) {
+        const subscriber = this.subscribers.get(name);
+        if (!subscriber)
+            return;
+        subscriber.reportedBytes = Math.max(0, bytes);
+        // Cheap check: if THIS subscriber's category is now over the
+        // high-water mark, start the pressure-tick. The full rebalance
+        // runs inside the tick to keep this call O(1).
+        const allocation = this.computeAllowedBytes(subscriber.category);
+        if (allocation > 0 && subscriber.reportedBytes >= allocation * CATEGORY_PRESSURE_HIGH) {
+            this.ensurePressureTickRunning();
+        }
+    }
+    /**
+     * 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() {
+        return { ...this.categoryShares };
+    }
+    /**
+     * 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) {
+        return this.computeAllowedBytes(category);
+    }
+    /**
+     * Start periodic rebalancing (every 30s). Aligns with brainy's existing
+     * memory pressure monitoring interval.
+     */
+    startRebalancing() {
+        if (this.rebalanceTimer)
+            return;
+        this.rebalanceTimer = setInterval(() => {
+            this.rebalance();
+        }, REBALANCE_INTERVAL_MS);
+        // Don't keep the process alive just for rebalancing
+        if (this.rebalanceTimer.unref) {
+            this.rebalanceTimer.unref();
+        }
+    }
+    /**
+     * Stop periodic rebalancing.
+     */
+    stopRebalancing() {
+        if (this.rebalanceTimer) {
+            clearInterval(this.rebalanceTimer);
+            this.rebalanceTimer = null;
+        }
+        this.stopPressureTick();
+    }
+    /**
+     * 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.
+     */
+    ensurePressureTickRunning() {
+        if (this.pressureTickTimer) {
+            this.quietTicks = 0;
+            return;
+        }
+        this.quietTicks = 0;
+        this.pressureTickTimer = setInterval(() => {
+            this.runPressureTick();
+        }, PRESSURE_TICK_INTERVAL_MS);
+        if (this.pressureTickTimer.unref) {
+            this.pressureTickTimer.unref();
+        }
+    }
+    stopPressureTick() {
+        if (this.pressureTickTimer) {
+            clearInterval(this.pressureTickTimer);
+            this.pressureTickTimer = null;
+        }
+        this.quietTicks = 0;
+    }
+    /**
+     * 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() {
+        this.runPressureTick();
+    }
+    // ── Instance tracking ────────────────────────────────────────────────────
+    /**
+     * 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, entityCount) {
+        const estimatedMemory = INSTANCE_BASELINE_BYTES + entityCount * this.observedBytesPerEntity();
+        this.instances.set(key, {
+            key,
+            entityCount,
+            estimatedMemory,
+            lastAccess: Date.now(),
+        });
+        this.rebalance();
+        this.maybeWarnOsLimits();
+    }
+    /**
+     * 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`.
+     */
+    maybeWarnOsLimits() {
+        if (this.osLimitsWarned)
+            return;
+        const n = this.instances.size;
+        if (n < 100)
+            return; // only matters once a real pool is running
+        const info = getOpenFileLimitInfo();
+        if (!info)
+            return;
+        // Post-lazy-shard per-brain estimates, with margin.
+        const projFds = n * 16;
+        const projMaps = n * 24;
+        const fdTight = info.hard > 0 && info.hard < projFds;
+        const mapTight = info.vmMaxMapCount > 0 && info.vmMaxMapCount < projMaps;
+        if (!fdTight && !mapTight)
+            return;
+        this.osLimitsWarned = true;
+        prodLog.warn(`[cor] ${n} brains pooled in one process — OS limits may bottleneck before RAM. ` +
+            `A process can't raise these; set them in the deployment:\n` +
+            `  docker run --ulimit nofile=65536:65536 --sysctl vm.max_map_count=262144 …\n` +
+            `  (current hard nofile=${info.hard}, vm.max_map_count=${info.vmMaxMapCount}; ` +
+            `cor already raised soft nofile to ${info.softAfter}). See cor ADR-004.`);
+    }
+    /**
+     * 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) {
+        this.instances.delete(key);
+        this.rebalance();
+    }
+    /**
+     * Record an access to an instance (updates lastAccess for weighted eviction).
+     *
+     * @param key - The scope key
+     */
+    touchInstance(key) {
+        const info = this.instances.get(key);
+        if (info) {
+            info.lastAccess = Date.now();
+        }
+    }
+    // ── Resource profiling ───────────────────────────────────────────────────
+    /**
+     * **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() {
+        const stats = v8.getHeapStatistics();
+        const ratio = stats.heap_size_limit > 0
+            ? stats.used_heap_size / stats.heap_size_limit
+            : 0;
+        let pressure = 'normal';
+        if (ratio >= V8_HEAP_PRESSURE_CRITICAL)
+            pressure = 'critical';
+        else if (ratio >= V8_HEAP_PRESSURE_ELEVATED)
+            pressure = 'elevated';
+        return {
+            usedHeapSize: stats.used_heap_size,
+            heapSizeLimit: stats.heap_size_limit,
+            externalMemory: stats.external_memory,
+            ratio,
+            pressure,
+        };
+    }
+    /**
+     * **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() {
+        return this.getHeapStats().pressure;
+    }
+    /**
+     * **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() {
+        return this.osMemoryProbe.snapshot();
+    }
+    /**
+     * 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) {
+        this.osMemoryProbe = probe;
+    }
+    /**
+     * Compute a full resource profile snapshot.
+     *
+     * @returns Current system resources, instance stats, and recommendations
+     */
+    getResourceProfile() {
+        const mem = process.memoryUsage();
+        const totalEntities = this.getTotalEntities();
+        const totalInstanceMemory = this.getTotalInstanceMemory();
+        const activeInstances = this.instances.size;
+        const recommendedCacheSize = this.computeCacheBudget(totalInstanceMemory);
+        const pressure = this.computePressure(mem.rss);
+        const usedByFixed = FIXED_OVERHEAD_BYTES;
+        const usedByInstances = totalInstanceMemory;
+        const usedByCache = recommendedCacheSize;
+        const headroom = Math.max(0, this.effectiveLimit - usedByFixed - usedByInstances - usedByCache);
+        const avgInstanceMemory = activeInstances > 0
+            ? totalInstanceMemory / activeInstances
+            : INSTANCE_BASELINE_BYTES;
+        return {
+            totalMemory: os.totalmem(),
+            freeMemory: os.freemem(),
+            effectiveLimit: this.effectiveLimit,
+            isContainer: this.isContainer,
+            processRss: mem.rss,
+            heapUsed: mem.heapUsed,
+            cpuCount: os.cpus().length,
+            activeInstances,
+            totalEntities,
+            recommendedCacheSize,
+            pressure,
+            avgInstanceMemory,
+            headroom,
+            v8Heap: this.getHeapStats(),
+            osMemory: this.getOsMemorySnapshot(),
+        };
+    }
+    /**
+     * 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 = 500) {
+        const profile = this.getResourceProfile();
+        const needed = INSTANCE_BASELINE_BYTES + estimatedEntities * this.observedBytesPerEntity();
+        return profile.headroom >= needed && profile.pressure !== 'critical';
+    }
+    /**
+     * **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.
+     */
+    observedBytesPerEntity() {
+        const totalEntities = this.getTotalEntities();
+        if (totalEntities === 0)
+            return FALLBACK_BYTES_PER_ENTITY;
+        let totalReported = 0;
+        for (const sub of this.subscribers.values()) {
+            totalReported += sub.reportedBytes;
+        }
+        if (totalReported === 0)
+            return FALLBACK_BYTES_PER_ENTITY;
+        const ratio = Math.floor(totalReported / totalEntities);
+        return Math.max(MIN_BYTES_PER_ENTITY, ratio);
+    }
+    /**
+     * 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() {
+        if (this.instances.size === 0)
+            return null;
+        const now = Date.now();
+        let bestKey = null;
+        let bestScore = -Infinity;
+        for (const [key, info] of this.instances) {
+            // Score: idle time weighted by memory usage
+            // Higher score = better eviction candidate
+            const idleMs = now - info.lastAccess;
+            const memoryWeight = info.estimatedMemory / (1024 * 1024); // MB
+            const score = (idleMs / 1000) * memoryWeight; // seconds × MB
+            if (score > bestScore) {
+                bestScore = score;
+                bestKey = key;
+            }
+        }
+        return bestKey;
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    rebalance() {
+        const totalInstanceMemory = this.getTotalInstanceMemory();
+        const newCacheSize = this.computeCacheBudget(totalInstanceMemory);
+        if (this.onCacheResize) {
+            try {
+                this.onCacheResize(newCacheSize);
+            }
+            catch {
+                // back-compat callback threw; protect the loop
+            }
+        }
+        this.notifySubscribers();
+    }
+    /**
+     * 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).
+     */
+    runPressureTick() {
+        const categoryBytes = this.aggregateReportedBytesByCategory();
+        const cacheBudget = this.computeCacheBudget(this.getTotalInstanceMemory());
+        let anyPressure = false;
+        // Identify donors (low utilization) and recipients (high utilization).
+        const donors = [];
+        const recipients = [];
+        for (const category of Object.keys(BASE_CATEGORY_SHARES)) {
+            const allocation = cacheBudget * this.categoryShares[category];
+            if (allocation <= 0)
+                continue;
+            const reported = categoryBytes[category];
+            const utilization = reported / allocation;
+            if (utilization >= CATEGORY_PRESSURE_HIGH) {
+                anyPressure = true;
+                recipients.push(category);
+            }
+            else if (utilization <= 1 - CATEGORY_PRESSURE_HIGH) {
+                // Symmetric low-water: a category using <10% of its allocation
+                // is a candidate donor. Lower threshold than the high-water on
+                // purpose — we don't want to flap on small fluctuations.
+                donors.push(category);
+            }
+        }
+        if (recipients.length > 0 && donors.length > 0) {
+            this.rebalanceShares(donors, recipients, categoryBytes, cacheBudget);
+        }
+        // Quiet-tick detection: if no category is over the LOW-water mark
+        // (i.e., everyone is using < 70% of their allocation), count it as
+        // a quiet tick. Three in a row → stop the pressure-tick.
+        const anyAboveLow = Object.keys(BASE_CATEGORY_SHARES).some((c) => {
+            const allocation = cacheBudget * this.categoryShares[c];
+            return allocation > 0 && categoryBytes[c] >= allocation * CATEGORY_PRESSURE_LOW;
+        });
+        if (anyAboveLow) {
+            this.quietTicks = 0;
+        }
+        else {
+            this.quietTicks++;
+            if (this.quietTicks >= 3) {
+                this.stopPressureTick();
+            }
+        }
+        // Always notify after a tick — subscribers should see the new
+        // ceiling even if we didn't shift shares this round (e.g. if a
+        // subscriber's reported bytes alone changed the allowed ceiling
+        // via the back-compat cache resize callback).
+        if (anyPressure || this.quietTicks === 0) {
+            this.notifySubscribers();
+        }
+    }
+    /**
+     * 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.
+     */
+    rebalanceShares(donors, recipients, categoryBytes, cacheBudget) {
+        // Pre-cap contributions: each donor's bounded contribution is the
+        // smaller of (headroom × 0.5) and (currentShare - minShare).
+        let totalContribution = 0;
+        const donorContributions = {};
+        for (const donor of donors) {
+            const allocation = cacheBudget * this.categoryShares[donor];
+            const reported = categoryBytes[donor];
+            const headroomShare = (allocation - reported) / cacheBudget;
+            const unboundedGive = Math.max(0, headroomShare * 0.5);
+            const baseShare = BASE_CATEGORY_SHARES[donor];
+            const minShare = baseShare * CATEGORY_MIN_SHARE;
+            const maxGive = Math.max(0, this.categoryShares[donor] - minShare);
+            const bounded = Math.min(unboundedGive, maxGive);
+            if (bounded > 0) {
+                donorContributions[donor] = bounded;
+                totalContribution += bounded;
+            }
+        }
+        if (totalContribution <= 0)
+            return;
+        // Pre-cap demands: each recipient's bounded demand is the smaller of
+        // (over-utilization + growth wish) and (maxShare - currentShare).
+        let totalDemand = 0;
+        const recipientDemands = {};
+        for (const recipient of recipients) {
+            const allocation = cacheBudget * this.categoryShares[recipient];
+            const reported = categoryBytes[recipient];
+            const overByShare = Math.max(0, (reported - allocation) / cacheBudget);
+            const growthWish = this.categoryShares[recipient] * 0.05;
+            const unboundedWant = overByShare + growthWish;
+            const baseShare = BASE_CATEGORY_SHARES[recipient];
+            const maxShare = baseShare * CATEGORY_MAX_SHARE;
+            const maxTake = Math.max(0, maxShare - this.categoryShares[recipient]);
+            const bounded = Math.min(unboundedWant, maxTake);
+            if (bounded > 0) {
+                recipientDemands[recipient] = bounded;
+                totalDemand += bounded;
+            }
+        }
+        if (totalDemand <= 0)
+            return;
+        // Transfer = min of bounded totals. Equally distributed across both
+        // sides → sum of give == sum of take → categoryShares sum is
+        // preserved without renormalization.
+        const transfer = Math.min(totalContribution, totalDemand);
+        for (const donor of donors) {
+            const contribution = donorContributions[donor];
+            if (!contribution)
+                continue;
+            const give = (contribution / totalContribution) * transfer;
+            this.categoryShares[donor] -= give;
+        }
+        for (const recipient of recipients) {
+            const demand = recipientDemands[recipient];
+            if (!demand)
+                continue;
+            const take = (demand / totalDemand) * transfer;
+            this.categoryShares[recipient] += take;
+        }
+        // Defensive renormalize only if float drift accumulated meaningfully
+        // (1e-9 threshold). Should be a no-op in steady state because the
+        // pre-capped transfer is symmetric.
+        this.renormalizeShares();
+    }
+    /**
+     * Compute the current allowed-bytes ceiling for a category.
+     */
+    computeAllowedBytes(category) {
+        const cacheBudget = this.computeCacheBudget(this.getTotalInstanceMemory());
+        return Math.floor(cacheBudget * this.categoryShares[category]);
+    }
+    /**
+     * Sum the reportedBytes of every subscriber by category.
+     */
+    aggregateReportedBytesByCategory() {
+        const totals = {
+            vectors: 0,
+            metadata: 0,
+            embedding: 0,
+            other: 0,
+        };
+        for (const sub of this.subscribers.values()) {
+            totals[sub.category] += sub.reportedBytes;
+        }
+        return totals;
+    }
+    /**
+     * 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.
+     */
+    notifySubscribers() {
+        for (const subscriber of this.subscribers.values()) {
+            const allowed = this.computeAllowedBytes(subscriber.category);
+            const delta = Math.abs(allowed - subscriber.lastAllowed);
+            const ratio = subscriber.lastAllowed > 0 ? delta / subscriber.lastAllowed : Infinity;
+            if (delta >= NOTIFY_DELTA_BYTES && ratio >= NOTIFY_DELTA_RATIO) {
+                subscriber.lastAllowed = allowed;
+                try {
+                    subscriber.callback(allowed);
+                }
+                catch {
+                    // foreign callback threw; swallow
+                }
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    renormalizeShares() {
+        const sum = this.categoryShares.vectors +
+            this.categoryShares.metadata +
+            this.categoryShares.embedding +
+            this.categoryShares.other;
+        if (sum <= 0)
+            return;
+        if (Math.abs(sum - 1) < 1e-9)
+            return;
+        this.categoryShares.vectors /= sum;
+        this.categoryShares.metadata /= sum;
+        this.categoryShares.embedding /= sum;
+        this.categoryShares.other /= sum;
+    }
+    /**
+     * 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.
+     */
+    computeCacheBudget(totalInstanceMemory) {
+        const available = this.effectiveLimit;
+        const afterFixed = available - FIXED_OVERHEAD_BYTES;
+        const afterInstances = afterFixed - totalInstanceMemory;
+        // Reserve 20% of remaining for headroom (new instances, spikes)
+        const forCache = afterInstances * 0.8;
+        // Also cap at MAX_CACHE_RATIO of total available (don't let cache dominate)
+        const ratioCap = afterFixed * MAX_CACHE_RATIO;
+        const cacheSize = Math.min(forCache, ratioCap);
+        return Math.max(MIN_CACHE_BYTES, Math.floor(cacheSize));
+    }
+    /**
+     * Determine memory pressure level from current RSS.
+     */
+    computePressure(rss) {
+        const ratio = rss / this.effectiveLimit;
+        if (ratio >= PRESSURE_CRITICAL)
+            return 'critical';
+        if (ratio >= PRESSURE_ELEVATED)
+            return 'elevated';
+        return 'normal';
+    }
+    getTotalEntities() {
+        let total = 0;
+        for (const info of this.instances.values()) {
+            total += info.entityCount;
+        }
+        return total;
+    }
+    getTotalInstanceMemory() {
+        let total = 0;
+        for (const info of this.instances.values()) {
+            total += info.estimatedMemory;
+        }
+        return total;
+    }
+}
+//# sourceMappingURL=ResourceManager.js.map