@soulcraft/cor 3.0.0-rc.1

package/dist/providerContracts.d.ts

@@ -0,0 +1,277 @@
+/**
+ * @module providerContracts
+ * @description Cor-local copies of brainy's provider contracts — the EXACT
+ * method/property surface brainy calls on each native provider cor registers.
+ *
+ * Cor's wrappers `implements` these, so dropping or drifting a member brainy
+ * depends on becomes a compile error here (not a runtime crash when the code
+ * path first runs with cor active). This is the compile-time half of the
+ * provider-parity guarantee; `scripts/check-brainy-compat.mjs` is the runtime
+ * half (it instantiates each provider and asserts the same surface).
+ *
+ * ## Why a local copy
+ *
+ * These interfaces are exported from brainy's `@soulcraft/brainy/plugin`
+ * entrypoint, but only from the brainy release that ships alongside cor
+ * 2.3.0 — they are NOT in published brainy 7.24.0, which cor currently
+ * builds against. So cor keeps a local copy (exactly as it already does for
+ * `ColumnStoreProvider` and `EntityIdMapperLike` in {@link module:utils/columnStoreTypes}
+ * and for the collation routine — see `docs/ADR-001`). The copies MUST stay in
+ * lockstep with brainy's `src/plugin.ts`. When cor bumps its brainy
+ * dependency to the release that exports them, replace this file's interface
+ * bodies with re-exports from `@soulcraft/brainy/plugin`:
+ *
+ * ```ts
+ * export type {
+ *   MetadataIndexProvider, GraphIndexProvider, HnswProvider,
+ *   EntityIdMapperProvider, CacheProvider,
+ * } from '@soulcraft/brainy/plugin'
+ * ```
+ *
+ * `AggregationProvider` is intentionally absent here: it is already a published
+ * export of brainy 7.24.0, so `NativeAggregationProvider` implements it directly
+ * from `@soulcraft/brainy`. `ColumnStoreProvider` likewise lives in
+ * {@link module:utils/columnStoreTypes} (its bitmap types reference cor's
+ * binary-compatible `RoaringBitmap32`).
+ */
+import type { Vector, VectorDocument, GraphVerb, NounType, VerbType } from '@soulcraft/brainy';
+import type { ColumnStoreProvider } from './utils/columnStoreTypes.js';
+/**
+ * @description The `'metadataIndex'` provider contract — the surface brainy
+ * calls via `this.metadataIndex.*` (plus the transactional add/remove
+ * operations). Mirror of brainy's `MetadataIndexProvider`.
+ */
+export interface MetadataIndexProvider {
+    init(): Promise<void>;
+    flush(): Promise<void>;
+    rebuild(): Promise<void>;
+    addToIndex(id: string, entityOrMetadata: any, skipFlush?: boolean, deferWrites?: boolean): Promise<void>;
+    removeFromIndex(id: string, metadata?: any): Promise<void>;
+    getIds(field: string, value: any): Promise<string[]>;
+    getIdsForFilter(filter: any, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<string[]>;
+    getIdsForTextQuery(query: string): Promise<Array<{
+        id: string;
+        matchCount: number;
+    }>>;
+    getSortedIdsForFilter(filter: any, orderBy: string, order?: 'asc' | 'desc', topK?: number): Promise<string[]>;
+    getFilterValues(field: string): Promise<string[]>;
+    getFilterFields(): Promise<string[]>;
+    getFieldValueForEntity(entityId: string, field: string): Promise<any>;
+    getFieldsForType(nounType: NounType): Promise<Array<{
+        field: string;
+        affinity: number;
+        occurrences: number;
+        totalEntities: number;
+    }>>;
+    getFieldStatistics(): Promise<Map<string, unknown>>;
+    getFieldsWithCardinality(): Promise<Array<{
+        field: string;
+        cardinality: number;
+        distribution: string;
+    }>>;
+    getOptimalQueryPlan(filters: Record<string, any>): Promise<unknown>;
+    /** Report which index path a `where` clause on `field` will hit (drives `brain.explain()`). */
+    explainField(field: string): Promise<{
+        path: 'column-store' | 'sparse-chunked' | 'none';
+        notes?: string;
+    }>;
+    getCountForCriteria(field: string, value: any): Promise<number>;
+    getEntityCountByType(type: string): number;
+    getEntityCountByTypeEnum(type: NounType): number;
+    getTotalEntityCount(): number;
+    getAllEntityCounts(): Map<string, number>;
+    getTopNounTypes(n: number): NounType[];
+    getTopVerbTypes(n: number): VerbType[];
+    getAllNounTypeCounts(): Map<NounType, number>;
+    getAllVerbTypeCounts(): Map<VerbType, number>;
+    getAllVFSEntityCounts(): Promise<Map<string, number>>;
+    detectAndRepairCorruption(): Promise<void>;
+    validateConsistency(): Promise<{
+        healthy: boolean;
+        avgEntriesPerEntity: number;
+        entityCount: number;
+        indexEntryCount: number;
+        recommendation: string | null;
+    }>;
+    /**
+     * O(1)-ish cross-bucket consistency probe. Brainy rc.6+ calls this ONCE on
+     * the first read; on `false` it runs `detectAndRepairCorruption()`. Returns
+     * `true` if healthy (or indeterminate), `false` if a cross-bucket phantom is
+     * sampled. Best-effort — never throws into the read path.
+     */
+    probeConsistency(): Promise<boolean>;
+    tokenize(text: string): string[];
+    extractTextContent(data: any): string;
+    getStats(): Promise<{
+        totalEntries: number;
+        totalIds: number;
+        fieldsIndexed: string[];
+        lastRebuild: number;
+        indexSize: number;
+    }>;
+    /** The shared UUID ↔ int mapper. Brainy reads `.getUuid(intId)` off the result. */
+    getIdMapper(): {
+        getUuid(intId: number): string | undefined;
+    };
+    /** The column store the coordinator delegates `where`/`orderBy` to. */
+    readonly columnStore: ColumnStoreProvider;
+}
+/**
+ * @description The `'graphIndex'` provider contract — the surface brainy calls
+ * via `this.graphIndex.*` (some optional-chained). Mirror of brainy's
+ * `GraphIndexProvider`.
+ *
+ * **Cor 3.0 Piece D**: entity ids cross as `bigint` (the canonical u64
+ * from brainy's `BinaryIdMapper`). Verb-ids likewise cross as `bigint`
+ * (the verb-int interned via cor's `verb_id_namespace`). Brainy 8.0
+ * owns UUID ↔ int conversion on its side via the same `BinaryIdMapper`
+ * it already maintains. The legacy string-id surface is retired —
+ * brainy 7.x consumers will not work against this contract.
+ */
+export interface GraphIndexProvider {
+    /** `false` until the index has loaded; brainy probes this before fast paths. */
+    readonly isInitialized: boolean;
+    /**
+     * Eagerly cold-load the durable graph (the four u64 LSM trees) from
+     * persistence. Brainy 8.0 (#36) awaits this right after
+     * `metadataIndex.init()` and BEFORE consulting {@link isReady}, so the
+     * rebuild gate reads an honest readiness signal. Idempotent and a no-op
+     * for an in-memory (no `persistence_dir`) index. Mirrors
+     * {@link MetadataIndexProvider.init}.
+     */
+    init(): Promise<void>;
+    /**
+     * Whether the graph's edges are loaded and queryable WITHOUT a rebuild —
+     * brainy's rebuild gate (#36). `true` once the durable cold-load restored
+     * the adjacency (so brainy SKIPS its O(E) rebuild-from-storage), or while
+     * live edges sit in a memtable. Edges-loaded semantics ONLY — never gated
+     * on the verb-id membership walk. Synchronous (no await).
+     */
+    isReady(): boolean;
+    getNeighbors(id: bigint, optionsOrDirection?: {
+        direction?: 'in' | 'out' | 'both';
+        limit?: number;
+        offset?: number;
+    } | 'in' | 'out' | 'both'): Promise<bigint[]>;
+    getVerbIdsBySource(sourceInt: bigint, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<bigint[]>;
+    getVerbIdsByTarget(targetInt: bigint, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<bigint[]>;
+    /** Resolve interned verb ints back to verb-id strings (null per missing int).
+     * brainy hard-calls this to hydrate edge verb-ids; mirrored here so the
+     * `implements` guard catches any future drift on it. (#79 cluster C.) */
+    verbIntsToIds(verbInts: bigint[]): Promise<(string | null)[]>;
+    getVerbsBatchCached(verbIds: string[]): Promise<Map<string, GraphVerb>>;
+    rebuild(): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    size(): number;
+    getStats(): {
+        totalRelationships: number;
+        sourceNodes: number;
+        targetNodes: number;
+        memoryUsage: number;
+        lastRebuild: number;
+        rebuildTime: number;
+    };
+    getRelationshipStats(): {
+        totalRelationships: number;
+        relationshipsByType: Record<string, number>;
+        uniqueSourceNodes: number;
+        uniqueTargetNodes: number;
+        totalNodes: number;
+    };
+    getRelationshipCountByType(type: string): number;
+    getTotalRelationshipCount(): number;
+    getAllRelationshipCounts(): Map<string, number>;
+}
+/**
+ * @description The object returned by the `'vector'` provider factory
+ * — the surface brainy hard-calls via `this.index.*` plus the
+ * transactional add/remove operations. Mirror of brainy 8.0's
+ * `VectorIndexProvider`.
+ *
+ * Cor's implementation is [[`NativeDiskAnnWrapper`]] (Adaptive
+ * DiskANN). Brainy 8.0 keeps its own pure-JS HNSW for the standalone
+ * open-source path (~10 M entities) — the contract name is shared
+ * vocabulary so brainy can swap implementations transparently.
+ *
+ * `enableCOW`, `getItem`, and `setPersistMode` are intentionally
+ * absent: brainy feature-detects each (`typeof x === 'function'`),
+ * so they are optional, not part of the required contract.
+ */
+export interface VectorIndexProvider {
+    addItem(item: VectorDocument): Promise<string>;
+    removeItem(id: string): Promise<boolean>;
+    search(queryVector: Vector, k?: number, filter?: (id: string) => Promise<boolean>, options?: {
+        rerank?: {
+            multiplier: number;
+        };
+        candidateIds?: string[];
+        /**
+         * **Predicate pushdown (#10).** The metadata∩graph universe (entity
+         * UUIDs) brainy's `find()` has already computed for this query. When
+         * supplied and selective, cor pushes it INTO the native beam walk
+         * (collect only allowed slots, walk wider) instead of post-filtering —
+         * far higher recall on selective filters. brainy feature-detects this:
+         * passing `allowedIds` is optional and a provider may ignore it (the
+         * pure-JS path falls back to `filter`). Coordinate the matching
+         * addition to brainy 8.0's `VectorIndexProvider.search` contract +
+         * `find()` wiring via PLATFORM-HANDOFF (CTX-PUSHDOWN-ALLOWEDIDS).
+         */
+        allowedIds?: ReadonlySet<string>;
+    }): Promise<Array<[string, number]>>;
+    size(): number;
+    clear(): void;
+    rebuild(options?: any): Promise<void>;
+    flush(): Promise<number>;
+    getPersistMode(): 'immediate' | 'deferred';
+}
+/**
+ * @description The `'entityIdMapper'` provider contract — a drop-in for brainy's
+ * `EntityIdMapper`. Injected into brainy's TypeScript `MetadataIndexManager`
+ * when a native metadata index is not also registered; that coordinator calls
+ * this full surface (incl. `getAllIntIds`, the all-ids universe brainy uses for
+ * negation / `exists:false` filters). Mirror of brainy's `EntityIdMapperProvider`.
+ */
+export interface EntityIdMapperProvider {
+    init(): Promise<void>;
+    getOrAssign(uuid: string): number;
+    getUuid(intId: number): string | undefined;
+    getInt(uuid: string): number | undefined;
+    remove(uuid: string): boolean;
+    flush(): Promise<void>;
+    clear(): Promise<void>;
+    getAllIntIds(): number[];
+    intsIterableToUuids(ints: Iterable<number>): string[];
+    readonly size: number;
+}
+/**
+ * @description Vector-index cache category union. Four hot working-
+ * set slices brainy + cor coordinate cache budget across:
+ * `'vectors'` (graph hops + PQ codes pages), `'metadata'` (LSM block
+ * cache), `'embedding'` (embedding model cache), and `'other'`
+ * (catch-all).
+ */
+export type CacheCategory = 'vectors' | 'metadata' | 'embedding' | 'other';
+/**
+ * @description The `'cache'` provider contract — a drop-in for
+ * brainy's `UnifiedCache`. Brainy installs it as the global cache
+ * (`setGlobalCache`) and calls this surface via `getGlobalCache()`.
+ * Mirror of brainy's `CacheProvider`.
+ */
+export interface CacheProvider {
+    getSync(key: string): any | undefined;
+    set(key: string, data: any, type: CacheCategory, size: number, rebuildCost?: number): void;
+    delete(key: string): boolean;
+    deleteByPrefix(prefix: string): number;
+    clear(type?: CacheCategory): void;
+}
+//# sourceMappingURL=providerContracts.d.ts.map

package/dist/providerContracts.js

@@ -0,0 +1,38 @@
+/**
+ * @module providerContracts
+ * @description Cor-local copies of brainy's provider contracts — the EXACT
+ * method/property surface brainy calls on each native provider cor registers.
+ *
+ * Cor's wrappers `implements` these, so dropping or drifting a member brainy
+ * depends on becomes a compile error here (not a runtime crash when the code
+ * path first runs with cor active). This is the compile-time half of the
+ * provider-parity guarantee; `scripts/check-brainy-compat.mjs` is the runtime
+ * half (it instantiates each provider and asserts the same surface).
+ *
+ * ## Why a local copy
+ *
+ * These interfaces are exported from brainy's `@soulcraft/brainy/plugin`
+ * entrypoint, but only from the brainy release that ships alongside cor
+ * 2.3.0 — they are NOT in published brainy 7.24.0, which cor currently
+ * builds against. So cor keeps a local copy (exactly as it already does for
+ * `ColumnStoreProvider` and `EntityIdMapperLike` in {@link module:utils/columnStoreTypes}
+ * and for the collation routine — see `docs/ADR-001`). The copies MUST stay in
+ * lockstep with brainy's `src/plugin.ts`. When cor bumps its brainy
+ * dependency to the release that exports them, replace this file's interface
+ * bodies with re-exports from `@soulcraft/brainy/plugin`:
+ *
+ * ```ts
+ * export type {
+ *   MetadataIndexProvider, GraphIndexProvider, HnswProvider,
+ *   EntityIdMapperProvider, CacheProvider,
+ * } from '@soulcraft/brainy/plugin'
+ * ```
+ *
+ * `AggregationProvider` is intentionally absent here: it is already a published
+ * export of brainy 7.24.0, so `NativeAggregationProvider` implements it directly
+ * from `@soulcraft/brainy`. `ColumnStoreProvider` likewise lives in
+ * {@link module:utils/columnStoreTypes} (its bitmap types reference cor's
+ * binary-compatible `RoaringBitmap32`).
+ */
+export {};
+//# sourceMappingURL=providerContracts.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