@soulcraft/cortex 2.7.2 → 2.7.3

package/dist/hnsw/NativeHNSWWrapper.js

@@ -96,9 +96,22 @@ export class NativeHNSWWrapper {
         const root = this.resolveRootDir();
         if (!root)
             return undefined;
-        const branch = this.storage?.currentBranch;
-        if (!branch)
+        const s = this.storage;
+        // Mirror brainy's OWN branch resolution EXACTLY (brainy.js `getCurrentBranch`:
+        // `this.storage.currentBranch || 'main'`):
+        //   - Non-COW storage has no `currentBranch` property → snapshot lives at root.
+        //   - COW storage (brainy >= 7.31, mandatory COW) resolves the branch as
+        //     `currentBranch || 'main'` and loads `_hnsw.bin` from
+        //     `branches/<branch>/entities/nouns/hnsw/`. `currentBranch` is UNSET by
+        //     default (only populated after an explicit fork/checkout).
+        // The previous `if (!branch) return root` wrote the snapshot to the tenant
+        // ROOT on a default brain while brainy loaded from `branches/main/…` — the
+        // snapshot was never found and the index rebuilt per-entity on every cold
+        // start (Memory deployed-line regression, re-flagged 3×). Defaulting to
+        // 'main' for COW storage makes write + load agree.
+        if (!('currentBranch' in s))
             return root;
+        const branch = s.currentBranch || 'main';
         return require('node:path').join(root, 'branches', String(branch), 'entities', 'nouns', 'hnsw');
     }
     /** Absolute path of the `_hnsw.bin` snapshot for the active branch, or null. */

package/dist/legacyLayoutGuard.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module legacyLayoutGuard
+ * @description Refuses to start when a cor 3.0 process is pointed
+ * at a directory that still holds cortex 2.x on-disk artifacts.
+ *
+ * The failure mode this prevents is the most dangerous in production:
+ * an operator deploys brainy 8.0 + cor 3.0 to a host whose data
+ * directory hasn't been migrated yet, the service starts,
+ * `brain.init()` fires, and either (a) crashes mid-init with a
+ * confusing low-level error from a shadow-page store, or (b) — worse —
+ * cortex's auto-engagement creates a new 3.0 file alongside the 2.x
+ * remnants, producing a half-migrated state that's harder to roll
+ * back than a clean stop.
+ *
+ * The guard runs at the top of `corPlugin.activate()`, before any
+ * provider registers. It scans the storage root for known cortex 2.x
+ * markers, and if any are found, throws a single error with the exact
+ * migration command the operator needs to run. **Throwing here is the
+ * point** — a service that won't start is recoverable; a service that
+ * starts on the wrong format isn't.
+ *
+ * The guard is no-op when:
+ *   - The storage adapter isn't filesystem-backed (cortex 2.x markers
+ *     are inherently filesystem-rooted; cloud adapters can't have
+ *     them).
+ *   - The storage root is empty (fresh install — no migration needed).
+ *   - Only cor 3.0 markers are present (the migration completed,
+ *     or this brain was created fresh on 3.0).
+ *
+ * The guard fires when:
+ *   - `_id_mapper/uuid_to_int.mkv` is a FILE (cortex 2.x). In cortex
+ *     3.0 this is a DIRECTORY containing the shadow-page head pointer
+ *     + base + delta.
+ *   - `_id_mapper/int_to_uuid.bin` is a FILE (cortex 2.x). Same
+ *     story — 3.0 makes this a directory.
+ *   - `_metadata/` contains the cortex 2.x JSON chunk envelope shape
+ *     without the 3.0 LSM shard subdirectory.
+ *   - HNSW provider artifacts exist alongside no DiskANN directory.
+ *
+ * Bypass: setting `COR_LEGACY_LAYOUT_GUARD=skip` (legacy `CORTEX_LEGACY_LAYOUT_GUARD` still honored) in the environment
+ * disables the guard. This exists for the migration script itself
+ * (which needs to be able to read the legacy layout to take its
+ * snapshot) and for emergency debugging. Production code should never
+ * set this.
+ */
+/**
+ * Storage shape we can inspect. Cortex plugin's
+ * `BrainyPluginContext.storage` exposes `getBinaryBlobPath` on
+ * filesystem-backed adapters; we use that to discover the root.
+ */
+interface StorageWithBlobPath {
+    getBinaryBlobPath?: (key: string) => string | null;
+}
+/**
+ * Public guard. Call at the top of `corPlugin.activate()` with
+ * the brainy storage adapter. Throws if cortex 2.x markers are
+ * present.
+ */
+export declare function assertNoLegacyLayout(storage: StorageWithBlobPath | null | undefined): void;
+export {};
+//# sourceMappingURL=legacyLayoutGuard.d.ts.map

package/dist/legacyLayoutGuard.js

@@ -0,0 +1,187 @@
+/**
+ * @module legacyLayoutGuard
+ * @description Refuses to start when a cor 3.0 process is pointed
+ * at a directory that still holds cortex 2.x on-disk artifacts.
+ *
+ * The failure mode this prevents is the most dangerous in production:
+ * an operator deploys brainy 8.0 + cor 3.0 to a host whose data
+ * directory hasn't been migrated yet, the service starts,
+ * `brain.init()` fires, and either (a) crashes mid-init with a
+ * confusing low-level error from a shadow-page store, or (b) — worse —
+ * cortex's auto-engagement creates a new 3.0 file alongside the 2.x
+ * remnants, producing a half-migrated state that's harder to roll
+ * back than a clean stop.
+ *
+ * The guard runs at the top of `corPlugin.activate()`, before any
+ * provider registers. It scans the storage root for known cortex 2.x
+ * markers, and if any are found, throws a single error with the exact
+ * migration command the operator needs to run. **Throwing here is the
+ * point** — a service that won't start is recoverable; a service that
+ * starts on the wrong format isn't.
+ *
+ * The guard is no-op when:
+ *   - The storage adapter isn't filesystem-backed (cortex 2.x markers
+ *     are inherently filesystem-rooted; cloud adapters can't have
+ *     them).
+ *   - The storage root is empty (fresh install — no migration needed).
+ *   - Only cor 3.0 markers are present (the migration completed,
+ *     or this brain was created fresh on 3.0).
+ *
+ * The guard fires when:
+ *   - `_id_mapper/uuid_to_int.mkv` is a FILE (cortex 2.x). In cortex
+ *     3.0 this is a DIRECTORY containing the shadow-page head pointer
+ *     + base + delta.
+ *   - `_id_mapper/int_to_uuid.bin` is a FILE (cortex 2.x). Same
+ *     story — 3.0 makes this a directory.
+ *   - `_metadata/` contains the cortex 2.x JSON chunk envelope shape
+ *     without the 3.0 LSM shard subdirectory.
+ *   - HNSW provider artifacts exist alongside no DiskANN directory.
+ *
+ * Bypass: setting `COR_LEGACY_LAYOUT_GUARD=skip` (legacy `CORTEX_LEGACY_LAYOUT_GUARD` still honored) in the environment
+ * disables the guard. This exists for the migration script itself
+ * (which needs to be able to read the legacy layout to take its
+ * snapshot) and for emergency debugging. Production code should never
+ * set this.
+ */
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+const CORTEX_SUBDIRS = ['_id_mapper', '_metadata', '_diskann', '_graph_adjacency'];
+/**
+ * Heuristic: cortex 2.x flat-file layout markers under `_id_mapper`.
+ * Cor 3.0 makes both of these directories instead.
+ */
+const LEGACY_ID_MAPPER_FILES = [
+    '_id_mapper/uuid_to_int.mkv',
+    '_id_mapper/int_to_uuid.bin',
+];
+/**
+ * Discover the storage root directory from the brainy
+ * `StorageAdapter`. Returns null for non-filesystem adapters (no
+ * legacy markers possible).
+ */
+function resolveStorageRoot(storage) {
+    if (!storage || typeof storage.getBinaryBlobPath !== 'function')
+        return null;
+    // Ask for a sentinel path; the returned path's parent is the
+    // storage root for our purposes.
+    const probe = storage.getBinaryBlobPath('__cortex_legacy_layout_guard_probe__');
+    if (!probe)
+        return null;
+    // The probe path doesn't exist; we want its containing directory.
+    // brainy's FileSystemStorage returns something like
+    // `${rootDirectory}/__cortex_legacy_layout_guard_probe__` or
+    // `${rootDirectory}/binaryBlobs/__cortex_legacy_layout_guard_probe__`.
+    // Walk up to the directory that contains `_id_mapper` or is the
+    // brain root.
+    let dir = probe;
+    // Strip the probe filename component.
+    dir = dir.replace(/\/[^/]+$/, '');
+    // If this is `binaryBlobs/`, go one more up.
+    if (dir.endsWith('/binaryBlobs')) {
+        dir = dir.slice(0, -'/binaryBlobs'.length);
+    }
+    if (!existsSync(dir))
+        return null;
+    return dir;
+}
+function findLegacyMarkers(root) {
+    const markers = [];
+    // (1) cortex 2.x flat-file id mapper layout.
+    for (const rel of LEGACY_ID_MAPPER_FILES) {
+        const p = join(root, rel);
+        if (!existsSync(p))
+            continue;
+        const stat = statSync(p);
+        if (stat.isFile()) {
+            markers.push({
+                path: p,
+                reason: `${rel} is a file (cortex 2.x format). ` +
+                    `Cor 3.0 expects this to be a directory (shadow-page LSM store).`,
+            });
+        }
+    }
+    // (2) cortex 2.x metadata index JSON chunk files at the metadata
+    // root, with no 3.0 LSM shard subdirectory.
+    const metadataDir = join(root, '_metadata');
+    if (existsSync(metadataDir) && statSync(metadataDir).isDirectory()) {
+        const entries = readdirSync(metadataDir);
+        const hasLsmShard = entries.some((e) => e === 'memtable' || e.startsWith('lsm-'));
+        const hasJsonChunks = entries.some((e) => e.endsWith('.json') || e.endsWith('.cidx'));
+        if (hasJsonChunks && !hasLsmShard) {
+            markers.push({
+                path: metadataDir,
+                reason: `${metadataDir} contains cortex 2.x JSON chunk files (.json/.cidx) but no 3.0 LSM shard layout. ` +
+                    `Cor 3.0's metadata index is LSM-tree-backed.`,
+            });
+        }
+    }
+    // (3) HNSW provider artifacts in `_diskann/` or root without DiskANN
+    // directory. The cortex 2.x HNSW provider wrote a `.hnsw` file at
+    // the root or under a `_hnsw/` subdirectory. Cor 3.0 writes
+    // `_diskann/` instead.
+    const candidateHnsw = readdirSync(root, { withFileTypes: true })
+        .filter((e) => e.isFile())
+        .filter((e) => e.name.endsWith('.hnsw'));
+    if (candidateHnsw.length > 0 && !existsSync(join(root, '_diskann'))) {
+        markers.push({
+            path: join(root, candidateHnsw[0].name),
+            reason: `${root} contains cortex 2.x HNSW provider files (.hnsw) with no 3.0 DiskANN directory. ` +
+                `Cor 3.0 uses Adaptive DiskANN as the default vector index.`,
+        });
+    }
+    return markers;
+}
+/**
+ * Public guard. Call at the top of `corPlugin.activate()` with
+ * the brainy storage adapter. Throws if cortex 2.x markers are
+ * present.
+ */
+export function assertNoLegacyLayout(storage) {
+    // Dual-read during the cortex→cor rename: COR_ preferred, legacy CORTEX_ honored.
+    if ((process.env.COR_LEGACY_LAYOUT_GUARD ?? process.env.CORTEX_LEGACY_LAYOUT_GUARD) === 'skip') {
+        return;
+    }
+    const root = resolveStorageRoot(storage);
+    if (!root)
+        return; // non-filesystem adapter or unresolvable; nothing to check
+    if (!existsSync(root))
+        return; // fresh install
+    const markers = findLegacyMarkers(root);
+    if (markers.length === 0)
+        return;
+    // Build the error message. The point is to be SO clear that an
+    // operator can act on it without reading docs.
+    const lines = [
+        '',
+        '╔══════════════════════════════════════════════════════════════════════════╗',
+        '║ Cor 3.0 cannot start: this storage directory holds cortex 2.x data.   ║',
+        '╚══════════════════════════════════════════════════════════════════════════╝',
+        '',
+        `Storage root: ${root}`,
+        '',
+        'Cortex 2.x markers found:',
+        ...markers.map((m) => `  • ${m.reason}`),
+        '',
+        'Cor 3.0 broke the on-disk format intentionally to ship snapshot-safe',
+        'shadow-page LSM stores + Adaptive DiskANN. Reading 2.x files in 3.0 is not',
+        'supported by design.',
+        '',
+        '🚨 Do NOT delete this directory. Your data is intact in the 2.x format.',
+        '',
+        'To migrate (zero data loss, ~10 minutes for Venue-scale brains):',
+        '',
+        '  node node_modules/@soulcraft/cor/scripts/migrate-cortex-2x-to-3x.mjs \\',
+        `    --brain-dir ${root} \\`,
+        `    --backup-dir ${root}/../backups/pre-3.0`,
+        '',
+        'Full migration guide: docs/migration-3.0.md',
+        'Venue-specific worked example in docs/migration-3.0.md § Worked example — Venue',
+        '',
+        'To rollback instead: downgrade @soulcraft/brainy + @soulcraft/cortex to',
+        'your previous versions (e.g. brainy@7.31.6 cortex@2.7.0) — no data',
+        'changes have happened yet because cor 3.0 refused to start.',
+        '',
+    ];
+    throw new Error(lines.join('\n'));
+}
+//# sourceMappingURL=legacyLayoutGuard.js.map

package/dist/resource/OsMemoryProbe.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @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").
+ */
+/**
+ * Snapshot of OS-level memory state at observation time. All byte
+ * fields are in absolute bytes (the on-disk units in `/proc/meminfo`
+ * are KiB; the parser converts).
+ */
+export interface OsMemorySnapshot {
+    /**
+     * Total physical RAM on the machine — the `MemTotal` line in
+     * `/proc/meminfo`, or `os.totalmem()` on non-Linux fallback.
+     */
+    totalBytes: number;
+    /**
+     * Memory the kernel reports as available for new allocations
+     * without swapping. On Linux ≥ 3.14, this is the `MemAvailable`
+     * line — accounts for reclaimable page cache + slab. On older
+     * kernels and on the os-fallback path, falls back to
+     * {@link freeBytes}.
+     *
+     * This is the load-bearing field for the Adaptive DiskANN mode
+     * selector: it answers "can this brain afford to keep PQ codes
+     * RAM-resident?".
+     */
+    availableBytes: number;
+    /**
+     * Physically free memory — the `MemFree` line in `/proc/meminfo`,
+     * or `os.freemem()` on non-Linux fallback. Smaller than
+     * {@link availableBytes} on a healthy Linux system because it
+     * excludes reclaimable page cache.
+     */
+    freeBytes: number;
+    /**
+     * `1 - (availableBytes / totalBytes)` clamped to `[0, 1]`. A high
+     * pressure score means little headroom for new allocations; the
+     * adaptive selector uses this as the primary mode-down signal.
+     */
+    pressureScore: number;
+    /**
+     * `'proc-meminfo'` when the values came from a successful
+     * `/proc/meminfo` read; `'os-fallback'` when the probe degraded
+     * to `os.totalmem()`/`os.freemem()`. Surface for diagnostics —
+     * a fallback snapshot is a hint that the deployment is on macOS
+     * or Windows.
+     */
+    source: 'proc-meminfo' | 'os-fallback';
+}
+/**
+ * Subset of `/proc/meminfo` lines the probe cares about. Returned by
+ * {@link parseMeminfo} so the snapshot composition stays unit-
+ * testable.
+ */
+export interface MeminfoFields {
+    totalKib?: number;
+    availableKib?: number;
+    freeKib?: number;
+}
+/**
+ * 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 declare function parseMeminfo(text: string): MeminfoFields | null;
+/**
+ * Build an {@link OsMemorySnapshot} from the parsed `/proc/meminfo`
+ * fields. Visible for tests; production callers use
+ * {@link OsMemoryProbe.snapshot}.
+ */
+export declare function snapshotFromMeminfo(fields: MeminfoFields): OsMemorySnapshot;
+/**
+ * Build the os-fallback snapshot from Node's `os` module. Visible
+ * for tests; production callers use {@link OsMemoryProbe.snapshot}.
+ */
+export declare function snapshotFromOs(): OsMemorySnapshot;
+/**
+ * Optional config for {@link OsMemoryProbe}. All fields are mainly
+ * for tests — production callers construct with defaults.
+ */
+export interface OsMemoryProbeOptions {
+    /**
+     * Cache TTL in milliseconds. The snapshot is reused for repeated
+     * calls within this window. Default 250 ms — comfortably below
+     * the ResourceManager's 5 s pressure-tick.
+     */
+    cacheMs?: number;
+    /**
+     * Override the `/proc/meminfo` reader. Tests inject custom text
+     * to exercise the parser's edge cases without touching the real
+     * filesystem.
+     */
+    procReader?: () => string | null;
+    /**
+     * Override the os-fallback snapshot generator. Tests use this to
+     * pin the fallback shape without depending on the host's actual
+     * `os.totalmem()` reading.
+     */
+    osFallback?: () => OsMemorySnapshot;
+    /**
+     * Override the wall clock used for cache expiry. Tests pass a
+     * controllable timestamp source to assert cache behaviour
+     * deterministically.
+     */
+    now?: () => number;
+}
+/**
+ * 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 declare class OsMemoryProbe {
+    private readonly cacheMs;
+    private readonly procReader;
+    private readonly osFallback;
+    private readonly now;
+    private cached;
+    constructor(options?: OsMemoryProbeOptions);
+    /**
+     * Latest memory snapshot. Cached for {@link OsMemoryProbeOptions.cacheMs}
+     * milliseconds; calls inside the window reuse the cached value.
+     */
+    snapshot(): OsMemorySnapshot;
+    /**
+     * 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(): void;
+}
+//# sourceMappingURL=OsMemoryProbe.d.ts.map

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';
+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 {
+        const { readFileSync } = require('node:fs');
+        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