@soulcraft/cor 3.0.13 → 3.0.15

package/dist/native/napi.js

@@ -11,6 +11,7 @@
  */
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { COR_VERSION } from '../version.js';
 let cachedBindings = null;
 /** Platform keys matching napi-rs build output */
 const PLATFORM_KEY_MAP = {
@@ -56,6 +57,7 @@ export function loadViaNapi() {
     try {
         const bindings = require(binaryPath);
         cachedBindings = bindings;
+        logVersionBannerOnce(binaryPath);
         return bindings;
     }
     catch (err) {
@@ -66,15 +68,33 @@ export function loadViaNapi() {
     try {
         const bindings = require(devPath);
         cachedBindings = bindings;
+        logVersionBannerOnce(devPath);
         return bindings;
     }
     catch (err) {
         failures.push(`  - ${devPath}: ${err instanceof Error ? err.message : String(err)}`);
     }
-    throw new Error(`Failed to load Brainy native module for ${key}:\n` +
+    throw new Error(`[cor v${COR_VERSION}] Failed to load native module for ${key}:\n` +
         `${failures.join('\n')}\n` +
         `Build locally: cd native && npm run build`);
 }
+/**
+ * One-line version banner at first successful native load — the on-box
+ * version check (Gate Zero) as a journal one-liner. COR_VERSION is a CODE
+ * constant, so a bundled service (bun-compiled memory) logs the version its
+ * bundle actually CONTAINS — the 2026-07-13 phantom deploy (a fresh-looking
+ * bundle carrying a stale engine, no way to tell on-box) becomes a grep of
+ * the boot log. Once per process; console.error (not prodLog) so it appears
+ * even under silent/quiet logger configs — it is operational evidence, not
+ * chatter.
+ */
+let versionBannerLogged = false;
+function logVersionBannerOnce(loadedFrom) {
+    if (versionBannerLogged)
+        return;
+    versionBannerLogged = true;
+    console.error(`[cor v${COR_VERSION}] native binary loaded (${loadedFrom})`);
+}
 /**
  * Synchronously load a Node.js built-in module.
  * Workaround for ESM dynamic import restrictions.

package/dist/utils/NativeMetadataIndex.js

@@ -2710,13 +2710,27 @@ export class MetadataIndexManager {
         let processed = 0;
         let sinceFlush = 0;
         let noMetadata = 0;
+        // Heal observability (CORTEX-RESTART-STRAND, memory's ask): a rebuild
+        // must never be silent for minutes — the operator cannot distinguish
+        // converging from stuck. Every 500 posted entities logs progress with
+        // the sustained rate, so a pathological per-item cost names itself in
+        // the journal in real time.
+        const startedAt = Date.now();
+        let lastProgressAt = 0;
+        const fetchPage = (c) => kind === 'noun'
+            ? this.storage.getNouns({ pagination: { limit: PAGE, cursor: c } })
+            : this.storage.getVerbs({ pagination: { limit: PAGE, cursor: c } });
+        // Prefetch pipeline: the NEXT canonical page is fetched while the
+        // CURRENT page indexes, so adapter enumeration latency overlaps the
+        // RAM-speed posting work instead of adding to it.
+        let pending = fetchPage(cursor);
         while (hasMore) {
-            const page = kind === 'noun'
-                ? await this.storage.getNouns({ pagination: { limit: PAGE, cursor } })
-                : await this.storage.getVerbs({ pagination: { limit: PAGE, cursor } });
+            const page = await pending;
             const items = page.items;
             if (items.length === 0)
                 break; // empty page = done (defensive backstop)
+            if (page.hasMore)
+                pending = fetchPage(page.nextCursor);
             const ids = items.map((it) => it.id);
             const md = await this.loadRebuildMetadataBatch(kind, ids);
             for (const it of items) {
@@ -2733,6 +2747,12 @@ export class MetadataIndexManager {
                 if (metadata) {
                     await this.addToIndex(it.id, metadata, true, true);
                     processed++;
+                    if (processed - lastProgressAt >= 500) {
+                        lastProgressAt = processed;
+                        const elapsedS = (Date.now() - startedAt) / 1000;
+                        prodLog.info(`[NativeMetadataIndex] rebuild(${kind}): ${processed} posted ` +
+                            `in ${elapsedS.toFixed(1)}s (${(processed / Math.max(elapsedS, 0.001)).toFixed(0)}/s)`);
+                    }
                     if (++sinceFlush >= 5000) {
                         await this.flushRebuildDirty();
                         sinceFlush = 0;
@@ -2743,9 +2763,12 @@ export class MetadataIndexManager {
                 }
             }
             hasMore = page.hasMore;
-            cursor = page.nextCursor;
             await this.yieldToEventLoop();
         }
+        const totalS = (Date.now() - startedAt) / 1000;
+        prodLog.info(`[NativeMetadataIndex] rebuild(${kind}): COMPLETE — ${processed} posted ` +
+            `in ${totalS.toFixed(1)}s (${(processed / Math.max(totalS, 0.001)).toFixed(0)}/s)` +
+            (noMetadata > 0 ? `, ${noMetadata} without metadata` : ''));
         if (noMetadata > 0) {
             prodLog.warn(`[NativeMetadataIndex] rebuild(${kind}): ${noMetadata} enumerated ` +
                 `entit${noMetadata === 1 ? 'y' : 'ies'} carried no canonical ` +
@@ -2793,16 +2816,29 @@ export class MetadataIndexManager {
         else if (this.storage.getVerbMetadataBatch) {
             return this.storage.getVerbMetadataBatch(ids);
         }
+        // Bounded-concurrency reads (16-way). The reads are independent, and a
+        // SERIAL per-id walk multiplies the adapter's per-op latency by N — on
+        // a slow adapter (memory-vm measured ~1s/op shapes) that turned a
+        // seconds-long heal into ~1s/entity (CORTEX-RESTART-STRAND, the
+        // 52-minute heal). Concurrency divides heal time by ~16 on ANY
+        // adapter; fail-loud is preserved (a faulted read rejects the whole
+        // batch via Promise.all — readRebuildMetadataOrThrow retries once then
+        // throws, never silently excludes).
         const m = new Map();
-        for (const id of ids) {
-            // Retry-once-then-throw (readRebuildMetadataOrThrow): a faulted
-            // read must fail the rebuild loudly, never silently exclude the
-            // entity — a swallowed fault here completed the rebuild
-            // under-posted (the strand bug re-created by its own healer).
-            const md = await this.readRebuildMetadataOrThrow(kind, id);
-            if (md)
-                m.set(id, md);
-        }
+        const CONCURRENCY = 16;
+        let next = 0;
+        const workers = Array.from({ length: Math.min(CONCURRENCY, ids.length) }, async () => {
+            for (;;) {
+                const i = next++;
+                if (i >= ids.length)
+                    break;
+                const id = ids[i];
+                const md = await this.readRebuildMetadataOrThrow(kind, id);
+                if (md)
+                    m.set(id, md);
+            }
+        });
+        await Promise.all(workers);
         return m;
     }
     /**

package/dist/utils/binaryIdMapperFactory.js

@@ -15,7 +15,7 @@
  * brain pays only for what it uses. This is the constant-RAM,
  * billion-scale store that replaces the resident JSON id-maps (#72).
  */
-import { existsSync } from 'node:fs';
+import { statSync } from 'node:fs';
 import { loadNativeModule } from '../native/index.js';
 /** Default storage key for the extendible-hash UUID → int file. */
 export const DEFAULT_UUID_TO_INT_KEY = '_id_mapper/uuid_to_int.mkv';
@@ -65,10 +65,17 @@ export function openOrCreateBinaryIdMapper(storage, opts = {}) {
     // Both files must exist together (paired write semantics). A
     // half-present state is crash corruption surfaced as an error,
     // never silently recreated.
+    //
+    // Fault-vs-absent (spine ADR-004 §4): the probes below THROW on any stat
+    // fault other than a clean ENOENT. `existsSync` returned false on
+    // EACCES/EIO/EMFILE too — and a double false routed to `create()`, which
+    // TRUNCATES both stores: a transient permissions blip (backup tool,
+    // scanner, remount) could wipe the brain's entire UUID↔int allocator.
+    // Deciding open-vs-create is only legal on certain knowledge.
     let mapper;
     let created;
-    const uuidFileExists = existsSync(uuidToIntPath);
-    const intFileExists = existsSync(intToUuidPath);
+    const uuidFileExists = durableFilePresent(uuidToIntPath, uuidToIntKey);
+    const intFileExists = durableFilePresent(intToUuidPath, intToUuidKey);
     if (uuidFileExists && intFileExists) {
         mapper = NativeBinaryIdMapper.openExisting(config);
         created = false;
@@ -91,4 +98,27 @@ export function openOrCreateBinaryIdMapper(storage, opts = {}) {
         created,
     };
 }
+/**
+ * Fault-discriminating existence probe for the id-mapper stores (spine
+ * ADR-004 §4). Returns `true`/`false` only on CERTAIN knowledge; any stat
+ * fault other than a clean ENOENT throws — because the caller's "neither
+ * file exists" branch invokes `create()`, which TRUNCATES, and a transient
+ * EACCES/EIO must never be allowed to masquerade as a fresh brain.
+ */
+function durableFilePresent(path, key) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return false;
+        throw new Error(`openOrCreateBinaryIdMapper: existence probe FAULTED for '${key}' ` +
+            `(${code ?? 'unknown'}) — refusing to decide open-vs-create on a ` +
+            `fault (create() truncates the brain's id allocator; a transient ` +
+            `IO/permissions fault must never wipe it). Restore storage health ` +
+            `and reopen. Cause: ${String(error)}`);
+    }
+}
 //# sourceMappingURL=binaryIdMapperFactory.js.map

package/dist/version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module version
+ * @description The package version as a CODE constant — deliberately not a
+ * `package.json` read. Consumers that bundle cor (bun-compiled services like
+ * memory) inline this literal at build time, so the version a process LOGS
+ * is provably the version its bundle CONTAINS. A runtime `package.json`
+ * lookup would report whatever file happens to sit near the bundle — the
+ * exact ambiguity behind the 2026-07-13 phantom-deploy incident, where a
+ * "fresh" bundle silently carried a stale engine and no on-box check could
+ * tell. `scripts/release.sh` bumps this in lockstep with `package.json`;
+ * `check:brainy`-style drift between the two fails the release.
+ */
+/** The @soulcraft/cor version this build was cut from. */
+export declare const COR_VERSION = "3.0.15";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,15 @@
+/**
+ * @module version
+ * @description The package version as a CODE constant — deliberately not a
+ * `package.json` read. Consumers that bundle cor (bun-compiled services like
+ * memory) inline this literal at build time, so the version a process LOGS
+ * is provably the version its bundle CONTAINS. A runtime `package.json`
+ * lookup would report whatever file happens to sit near the bundle — the
+ * exact ambiguity behind the 2026-07-13 phantom-deploy incident, where a
+ * "fresh" bundle silently carried a stale engine and no on-box check could
+ * tell. `scripts/release.sh` bumps this in lockstep with `package.json`;
+ * `check:brainy`-style drift between the two fails the release.
+ */
+/** The @soulcraft/cor version this build was cut from. */
+export const COR_VERSION = '3.0.15';
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.13",
+  "version": "3.0.15",
   "description": "Native Rust acceleration for Brainy — SIMD distance, vector quantization, zero-copy mmap, native embeddings. Free tier for storage, Pro license for compute acceleration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",