@soulcraft/cor 3.0.21 → 3.0.22

package/dist/utils/NativeMetadataIndex.js

@@ -1145,28 +1145,52 @@ export class MetadataIndexManager {
     // Initialization
     // ==========================================================================
     async init() {
+        // Init-phase narration (loop-termination doctrine): every phase of
+        // open stamps its elapsed time on the ops channel, so a slow or
+        // wedged boot names its own phase instead of presenting as a silent
+        // hang after the last incidental log line (the 2026-07-18 incident
+        // burned two gate-hours localizing a freeze that one of these
+        // lines would have named instantly). Threshold-gated: a phase
+        // faster than INIT_PHASE_NARRATE_MS stays silent — narration in
+        // proportion to the work.
+        const initStarted = Date.now();
+        let phaseStarted = initStarted;
+        const INIT_PHASE_NARRATE_MS = 1000;
+        const phase = (name) => {
+            const now = Date.now();
+            if (now - phaseStarted >= INIT_PHASE_NARRATE_MS) {
+                opsLine(`init phase '${name}' took ${((now - phaseStarted) / 1000).toFixed(1)}s ` +
+                    `(${((now - initStarted) / 1000).toFixed(1)}s total)`);
+            }
+            phaseStarted = now;
+        };
         // **Piece 11 closeout.** Detect cortex 2.x legacy JSON metadata state on
         // disk. The cor 3.0 LSM engine is the only metadata engine, so an
         // un-migrated 2.x brain would have its on-disk JSON state shadowed and
         // surface as a mysteriously-empty brain on first query. Throw a clear
         // migration error instead so the operator runs the migration script.
         await this.detectLegacyJsonStateAndGate();
+        phase('legacy-gate');
         // Load field registry to discover persisted indices
         await this.loadFieldRegistry();
+        phase('field-registry');
         // #72 Phase C: build the shared mmap BinaryIdMapper from the brain's
         // `_id_mapper/*` paths and inject it as the core's canonical
         // UUID ↔ entity-int allocator. Must run before columnStore.init (which
         // resolves ids through getIdMapper()) and before any mutation.
         this.wireIdMapper();
+        phase('id-mapper');
         // ADR-004 §7: declare this provider's protected families (feature-
         // detected on brainy ≥8.3.0; idempotent upsert; loud-but-non-blocking).
         await declareDerivedFamilies(this.storage, METADATA_FAMILIES);
+        phase('family-declarations');
         // LSM durability (steps 3-4): open the native LSM engine here (not in the
         // constructor) so it can be seeded from the on-disk manifest and cold-load
         // every persisted SSTable into its live read set — the entire restore,
         // with NO O(N) rebuild. Runs after wireIdMapper (the engine's posting
         // lists reference the mapper's entity ints) and before any read/mutation.
         await this.openLsmEngine();
+        phase('lsm-open');
         // LOST-MAPPER GUARD (MEMORY-COR-IDMAP-MIGRATION, root-caused
         // 2026-07-14): the ONE genuinely dangerous open-state — the mmap
         // mapper was just created EMPTY while durable int-keyed postings
@@ -1205,17 +1229,20 @@ export class MetadataIndexManager {
         // or an absent/corrupt marker) does any further work. See
         // {@link guardIndexEpoch}.
         await this.guardIndexEpoch();
+        phase('epoch-guard');
         // Initialize the column store with the shared storage + id mapper façade.
         // Discovers any persisted `_column_index/` segments and re-applies tombstones.
         // Done before the rebuild branch below so that a rebuild repopulates a
         // freshly-initialized column store via addToIndex.
         await this.columnStore.init(this.storage, this.getIdMapper());
+        phase('column-store');
         const hasFields = this.knownFields.size > 0;
         if (!hasFields) {
             // Don't trust "empty" — field registry may be missing due to interrupted flush.
             // Probe storage for actual entities before concluding the workspace is empty.
             try {
                 const probe = await this.storage.getNouns({ pagination: { limit: 1, offset: 0 } });
+                phase('entity-probe');
                 const hasEntities = (probe.totalCount ?? 0) > 0 || probe.items.length > 0;
                 if (hasEntities) {
                     // **LSM durability (step 6) — rebuild demoted to disaster-recovery.**
@@ -1239,6 +1266,7 @@ export class MetadataIndexManager {
                         // lines). The strand check is boot-path-invariant: it runs
                         // here too, with the same verified-unpostable allowance.
                         await this.detectDerivedStrand();
+                        phase('strand-detect');
                         this.readinessInitialized = true;
                         return;
                     }
@@ -1266,8 +1294,10 @@ export class MetadataIndexManager {
                     catch {
                         // marker read failed — fall through to the normal rebuild path
                     }
+                    phase('format-marker');
                     console.warn(`[NativeMetadataIndex] Field registry missing but ${probe.totalCount ?? 'unknown'} entities exist — rebuilding index`);
                     await this.rebuild();
+                    phase('rebuild');
                     // A completed rebuild IS the readiness determination for this
                     // open (sweep finding: these early exits previously left
                     // readinessInitialized false — a fresh-rebuilt brain reported
@@ -1287,7 +1317,9 @@ export class MetadataIndexManager {
             return;
         }
         await this.warmCache();
+        phase('warm-cache');
         await this.lazyLoadCounts();
+        phase('lazy-counts');
         this.syncTypeCountsToFixed();
         // Strand detection (CORTEX-CONSOLIDATION-SILENT-DROP): the LSM can load
         // "durable state" that is silently MISSING postings — deleted shard logs
@@ -1296,6 +1328,7 @@ export class MetadataIndexManager {
         // contract reports ready, so brainy's gate heals via rebuild-from-
         // canonical instead of trusting a partial index.
         await this.detectDerivedStrand();
+        phase('strand-detect');
         // **#18 migration kick — LAST, after the index is fully constructed.** If the
         // epoch guard flagged a large stale brain (outcome 4), start the coordinated
         // blocking migration NOW: `start()` flips the lock (`isMigrating()` → true)
@@ -1327,6 +1360,7 @@ export class MetadataIndexManager {
                 this.lostMapperHeal = false;
                 if (coordinator) {
                     await coordinator.start();
+                    phase('lost-mapper-heal');
                 }
                 // No coordinator (raw/test usage): strandDetected already gates
                 // the metadata leg; the loud LOST-MAPPER ops line stands.
@@ -1434,6 +1468,20 @@ export class MetadataIndexManager {
     async detectDerivedStrand() {
         if (!this.lsmEngine || !this.lsmMetaDir)
             return;
+        // Stage narration (loop-termination doctrine, same contract as init's
+        // phase stamps): every stage of this detector that touches storage or
+        // the fact log stamps its elapsed time on the ops channel when it
+        // exceeds 1s, so a slow open names its stage instead of presenting as
+        // a silent hang after init's 'column-store' line. Threshold-gated —
+        // narration in proportion to the work.
+        let stageStarted = Date.now();
+        const stage = (name) => {
+            const now = Date.now();
+            if (now - stageStarted >= 1000) {
+                opsLine(`strand-detect stage '${name}' took ${((now - stageStarted) / 1000).toFixed(1)}s`);
+            }
+            stageStarted = now;
+        };
         // M3 PD-4 (Stage 1): a coherent-but-BEHIND family stamp means the
         // postings simply predate the newest commits — replay EXACTLY the gap
         // from the generation fact log before any strand verdict, so the
@@ -1444,18 +1492,26 @@ export class MetadataIndexManager {
         try {
             const fns = await familyStampFns();
             const head = await readCommittedGeneration(this.storage);
+            stage('replay-precheck');
             if (fns && head !== undefined) {
                 const stamp = (await fns.readFamilyStamp(this.storage, METADATA_STAMP_PATH));
                 const src = stamp?.family === METADATA_FAMILY ? stamp.sourceGeneration : undefined;
+                stage('stamp-read');
                 if (typeof src === 'number' && src < head) {
-                    if (await this.replayFactGap(src + 1)) {
+                    const replayed = await this.replayFactGap(src + 1);
+                    stage('fact-replay');
+                    if (replayed) {
                         await this.persistMetadataStamp();
+                        stage('stamp-persist');
                     }
                 }
             }
         }
         catch {
-            // Detector below stays authoritative.
+            // Detector below stays authoritative. The stage marker still fires
+            // so a slow-then-faulted stamp read/replay is attributed HERE, not
+            // silently rolled into the next stage's elapsed time.
+            stage('m3-replay-fault');
         }
         // 0. Replay-stats verdict (3.0.12). The native open now RECREATES a
         // missing live log and recovers what its archives hold, so the
@@ -1487,6 +1543,7 @@ export class MetadataIndexManager {
         catch {
             // Verdict probe is advisory — a stats read failure must not block open.
         }
+        stage('replay-verdict');
         // 1. Archive-orphan census over the memtable shard logs.
         try {
             const memtableDir = join(this.lsmMetaDir, 'memtable');
@@ -1513,11 +1570,13 @@ export class MetadataIndexManager {
         catch {
             // Census is advisory — an unreadable dir must not block open.
         }
+        stage('archive-census');
         // 2. |canonical| == |posted| invariant.
         try {
             const getNouns = this.storage.getNouns;
             if (typeof getNouns === 'function') {
                 const probe = await getNouns.call(this.storage, { pagination: { limit: 1 } });
+                stage('canonical-probe');
                 const canonical = probe?.totalCount;
                 if (typeof canonical === 'number' &&
                     Number.isFinite(canonical) &&
@@ -1536,6 +1595,7 @@ export class MetadataIndexManager {
                     for (const t of Object.values(NounType)) {
                         posted += this.native.getEntityCountByType(t);
                     }
+                    stage('posted-count');
                     // LOWER-BOUND invariant, not equality: the adapter's totalCount
                     // EXCLUDES system-routed entities (e.g. the VFS root) while the
                     // index posts them, so healthy brains sit at posted ≥ canonical.
@@ -1555,6 +1615,7 @@ export class MetadataIndexManager {
                     // count-only and the allowance carries a bounded, logged
                     // staleness caveat.
                     const unpostable = await this.verifiedUnpostableAllowance();
+                    stage('unpostable-allowance');
                     if (posted + unpostable < canonical) {
                         this.strandDetected = true;
                         prodLog.error(`[NativeMetadataIndex] STRAND: canonical holds ${canonical} ` +
@@ -1575,6 +1636,7 @@ export class MetadataIndexManager {
         catch {
             // Invariant probe is advisory — a failed canonical read must not block open.
         }
+        stage('count-invariant');
     }
     // ==========================================================================
     // Storage I/O helpers
@@ -1837,7 +1899,11 @@ export class MetadataIndexManager {
     // Cache warming
     // ==========================================================================
     async warmCache() {
+        // Elapsed-time narration: each warm stage is a loop of per-field
+        // storage reads — stamp it when it exceeds 1s so a slow warm names
+        // itself instead of hiding inside init's 'warm-cache' phase total.
         const commonFields = ['noun', 'type', 'service', 'createdAt'];
+        const t0 = Date.now();
         await Promise.all(commonFields.map(async (field) => {
             try {
                 await this.ensureFieldLoaded(field);
@@ -1846,7 +1912,15 @@ export class MetadataIndexManager {
                 prodLog.debug(`Cache warming: field '${field}' not yet indexed`);
             }
         }));
+        if (Date.now() - t0 >= 1000) {
+            opsLine(`warm-cache: common-field load (${commonFields.length} fields) took ` +
+                `${((Date.now() - t0) / 1000).toFixed(1)}s`);
+        }
+        const t1 = Date.now();
         await this.warmCacheForTopTypes(3);
+        if (Date.now() - t1 >= 1000) {
+            opsLine(`warm-cache: top-type field load took ${((Date.now() - t1) / 1000).toFixed(1)}s`);
+        }
     }
     async warmCacheForTopTypes(topN = 3) {
         const topTypes = this.getTopNounTypes(topN);
@@ -1881,12 +1955,17 @@ export class MetadataIndexManager {
             this.entityCountsByTypeFixed.fill(0);
             this.verbCountsByTypeFixed.fill(0);
             // Ensure 'noun' field is loaded into Rust
+            const t0 = Date.now();
             await this.ensureFieldLoaded('noun');
+            if (Date.now() - t0 >= 1000) {
+                opsLine(`lazy-counts: 'noun' field load took ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+            }
             // Use Rust to get type counts via the noun field. Count natively
             // (#78 pt2) — getIdsCount returns the mapped-id count without
             // materializing one UUID string per entity. At 10B this is the
             // difference between O(1) per type and allocating billions of strings
             // just to read `.length`.
+            const t1 = Date.now();
             const nounValues = this.native.getFilterValues('noun');
             for (const typeName of nounValues) {
                 const count = this.native.getIdsCount('noun', JSON.stringify(typeName));
@@ -1894,6 +1973,10 @@ export class MetadataIndexManager {
                     this.totalEntitiesByType.set(typeName, count);
                 }
             }
+            if (Date.now() - t1 >= 1000) {
+                opsLine(`lazy-counts: type-count scan over ${nounValues.length} noun value(s) took ` +
+                    `${((Date.now() - t1) / 1000).toFixed(1)}s`);
+            }
             prodLog.debug(`Loaded type counts: ${this.totalEntitiesByType.size} types`);
         }
         catch (error) {
@@ -2791,10 +2874,82 @@ export class MetadataIndexManager {
             return false;
         let upserts = 0;
         let removals = 0;
+        let batches = 0;
+        let lastNarrated = 0;
+        const replayStarted = Date.now();
+        // Entry marker + first-batch liveness budget. The replay is ADVISORY
+        // (false = the walk heals, always authoritative), so the scan's FIRST
+        // batch gets a hard arrival budget: on a generation-backlogged brain
+        // the storage-side scan wedged indefinitely before its first batch,
+        // and the every-200 line below never fired — init froze silently
+        // inside this await (2026-07-19). An optional answer must never be a
+        // mandatory wait.
+        // Proportionality: the routine catch-up (a boot replaying its own
+        // last write, gap of a few generations, milliseconds) stays SILENT —
+        // the suite's boots-2+-are-clean contract treats new boot noise as
+        // heal activity, and it is right to. The entry line is deferred to
+        // the first liveness event ≥1s; the budget abort always speaks.
+        const FIRST_BATCH_BUDGET_MS = 120_000;
+        // TOTAL wall-clock budget: the replay is an OPTIMIZATION over the
+        // census walk, never a requirement — the walk stays authoritative
+        // and heals in minutes. The batch-arrival budget alone missed the
+        // second failure shape (2026-07-19): the scan produced batches fine
+        // but the per-op index work ground at ~7s/record on a mint-storm-
+        // scarred mapper — 321 upserts in 39 minutes against a 7,531-
+        // generation gap, a replay that could NEVER beat the walk it was
+        // optimizing away. Checked between ops: past the budget, abort
+        // loudly to the walk.
+        const TOTAL_REPLAY_BUDGET_MS = 300_000;
+        const iterator = scan.batches()[Symbol.asyncIterator]();
         try {
-            for await (const batch of scan.batches()) {
+            for (;;) {
+                let timer;
+                const budget = new Promise((resolve) => {
+                    timer = setTimeout(() => resolve('BUDGET'), FIRST_BATCH_BUDGET_MS);
+                    timer.unref?.();
+                });
+                const next = await Promise.race([iterator.next(), budget]);
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                if (next === 'BUDGET') {
+                    opsLine(`fact replay from generation ${fromGeneration} ABORTED — the scan ` +
+                        `produced no batch within ${FIRST_BATCH_BUDGET_MS / 1000}s ` +
+                        `(${batches} batches arrived before the stall); the storage ` +
+                        `fact-scan path is unhealthy on this brain — falling back to ` +
+                        `the walk-based heal, which is always authoritative`);
+                    return false;
+                }
+                if (next.done)
+                    break;
+                const batch = next.value;
+                // Liveness narration (loop-termination doctrine): a long replay
+                // must narrate. If the loop wedges mid-batch, the LAST line's
+                // counts localize the wedge; if scan.batches() itself stops
+                // producing, this line's ABSENCE (after the caller's stage stamp)
+                // localizes the producer instead.
+                batches++;
+                {
+                    // At most one liveness line per second, and none at all for a
+                    // sub-second replay — loud in proportion to the work.
+                    const now = Date.now();
+                    if (now - replayStarted >= 1000 && now - lastNarrated >= 1000) {
+                        lastNarrated = now;
+                        opsLine(`fact replay: ${batches} batch(es) from generation ${fromGeneration}, ` +
+                            `${upserts} upserts + ${removals} removals so far, ` +
+                            `${((now - replayStarted) / 1000).toFixed(1)}s elapsed`);
+                    }
+                }
                 for (const fact of batch.facts) {
                     for (const op of fact.ops) {
+                        if (Date.now() - replayStarted > TOTAL_REPLAY_BUDGET_MS) {
+                            opsLine(`fact replay from generation ${fromGeneration} ABORTED — ` +
+                                `${upserts} upserts + ${removals} removals consumed the ` +
+                                `${TOTAL_REPLAY_BUDGET_MS / 1000}s total budget with the gap ` +
+                                `unfinished; this replay cannot beat the walk it optimizes ` +
+                                `away — falling back to the walk-based heal, which is ` +
+                                `always authoritative`);
+                            return false;
+                        }
                         if (op.record === null) {
                             await this.removeFromIndex(op.id);
                             removals++;

package/dist/utils/generationWatermark.js

@@ -10,6 +10,15 @@
  * means the stamp carries no sourceGeneration and verifiers skip the
  * comparison — never a blocked write, never a guessed value.
  */
+/**
+ * Hard ceiling on the manifest-read fallback. The watermark is ADVISORY
+ * by contract (`undefined` = stamp carries no sourceGeneration, verifier
+ * skips) — so a storage layer that cannot answer promptly must cost a
+ * bounded wait and a loud line, never a frozen open (2026-07-19: a real
+ * brain state wedged this read indefinitely and init froze inside it,
+ * silent, until an external kill).
+ */
+const MANIFEST_READ_BUDGET_MS = 30_000;
 /** Best-effort committed watermark; `undefined` when unknowable. */
 export async function readCommittedGeneration(storage) {
     try {
@@ -24,7 +33,22 @@ export async function readCommittedGeneration(storage) {
         }
         if (typeof s?.readRawObject !== 'function')
             return undefined;
-        const manifest = (await s.readRawObject('_system/manifest.json'));
+        let timer;
+        const budget = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                console.error(`[cor] watermark: manifest read exceeded its ${MANIFEST_READ_BUDGET_MS / 1000}s ` +
+                    `budget — proceeding WITHOUT a sourceGeneration (advisory contract); ` +
+                    `the storage layer's read path is unhealthy and should be investigated`);
+                resolve(undefined);
+            }, MANIFEST_READ_BUDGET_MS);
+            timer.unref?.();
+        });
+        const manifest = (await Promise.race([
+            s.readRawObject('_system/manifest.json'),
+            budget,
+        ]));
+        if (timer !== undefined)
+            clearTimeout(timer);
         const g = manifest?.generation;
         return typeof g === 'number' && Number.isFinite(g) && g >= 0 ? g : undefined;
     }

package/dist/version.d.ts

@@ -11,5 +11,5 @@
  * `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.21";
+export declare const COR_VERSION = "3.0.22";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -11,5 +11,5 @@
  * `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.21';
+export const COR_VERSION = '3.0.22';
 //# sourceMappingURL=version.js.map

package/native/index.d.ts

@@ -121,8 +121,10 @@ export declare class NativeBinaryIdMapper {
    */
   getOrAssign(uuid: Buffer): number
   /**
-   * Lookup the int for `uuid`. Returns null if not present. Throws
-   * in `IdSpace::U64` mode — use [`get_int_big`].
+   * Lookup the int for `uuid`. Returns null only when the mapping
+   * is PROVEN absent; an unreadable store throws instead of
+   * masquerading as null. Throws in `IdSpace::U64` mode — use
+   * [`get_int_big`].
    */
   getInt(uuid: Buffer): number | null
   /**
@@ -156,7 +158,10 @@ export declare class NativeBinaryIdMapper {
    * a JS number).
    */
   getOrAssignBig(uuid: Buffer): bigint
-  /** BigInt sibling of [`get_int`]. */
+  /**
+   * BigInt sibling of [`get_int`]. Same null contract: null =
+   * proven absent, unreadable store = throw.
+   */
   getIntBig(uuid: Buffer): bigint | null
   /** BigInt sibling of [`get_uuid`]. */
   getUuidBig(int: bigint): Buffer | null
@@ -1796,7 +1801,8 @@ export declare class NativeMetadataIndex {
   uuidToInt(uuid: string): number | null
   /**
    * BigInt sibling of [`uuid_to_int`]. Works for both U32 and U64
-   * brains; preferred by brainy 8.0 consumers.
+   * brains; preferred by brainy 8.0 consumers. Null means PROVEN
+   * unmapped; an unreadable mapper store throws.
    */
   uuidToIntBig(uuid: string): bigint | null
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.21",
+  "version": "3.0.22",
   "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",
@@ -82,7 +82,7 @@
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.0.0",
-    "@soulcraft/brainy": "8.5.2",
+    "@soulcraft/brainy": "8.7.0",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",