@soulcraft/cor 3.0.16 → 3.0.17

package/dist/utils/NativeMetadataIndex.d.ts

@@ -563,6 +563,16 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      *    same rebuild). Skipped at/above the u32 saturation point of
      *    `getTotalEntityCount` (a saturated count would make equality lie).
      */
+    /**
+     * The verified-unpostable allowance for posted-vs-canonical floors: how
+     * many canonical noun rows the last COMPLETED rebuild PROVED carry no
+     * readable metadata (each verified by direct read at rebuild time, each
+     * RE-VERIFIED here so an id that has since gained metadata stops
+     * counting). Beyond {@link UNPOSTABLE_ID_CAP} the stamp is count-only
+     * and the allowance carries a bounded, logged staleness caveat.
+     * Advisory: any fault reads as 0 (may over-heal, never under-detects).
+     */
+    private verifiedUnpostableAllowance;
     private detectDerivedStrand;
     /**
      * **#72 Phase C.** Build the shared mmap `BinaryIdMapper` from the

package/dist/utils/NativeMetadataIndex.js

@@ -73,6 +73,20 @@ const LSM_MANIFEST_VERSION = 2;
  * field registry already depends on.
  */
 const LSM_MANIFEST_KEY = '__metadata_lsm_manifest__';
+/**
+ * Durable stamp of the entities a COMPLETED rebuild verified as
+ * unpostable (canonical rows with NO readable metadata — verified by
+ * direct read, not invented postings). The strand detector's
+ * posted-count floor accounts for them: without this, a fixed cohort of
+ * metadata-less canonical rows makes EVERY boot read as stranded and
+ * re-triggers a pointless full heal forever (memory-vm's constant-52,
+ * CORTEX-RESTART-STRAND 2026-07-13 — four consecutive boots).
+ */
+const UNPOSTABLE_STAMP_KEY = '__metadata_verified_unpostable__';
+/** Above this many ids the stamp stores count-only (the boot-time
+ * re-verify would stop being cheap); detection then carries a bounded
+ * staleness caveat, logged when it engages. */
+const UNPOSTABLE_ID_CAP = 1000;
 /**
  * **LSM durability (step 5).** Lower clamp (32 MiB) for the bounded-memtable
  * size-flush trigger. Even when the dynamic 'metadata' budget is tiny, the
@@ -1275,6 +1289,41 @@ export class MetadataIndexManager {
      *    same rebuild). Skipped at/above the u32 saturation point of
      *    `getTotalEntityCount` (a saturated count would make equality lie).
      */
+    /**
+     * The verified-unpostable allowance for posted-vs-canonical floors: how
+     * many canonical noun rows the last COMPLETED rebuild PROVED carry no
+     * readable metadata (each verified by direct read at rebuild time, each
+     * RE-VERIFIED here so an id that has since gained metadata stops
+     * counting). Beyond {@link UNPOSTABLE_ID_CAP} the stamp is count-only
+     * and the allowance carries a bounded, logged staleness caveat.
+     * Advisory: any fault reads as 0 (may over-heal, never under-detects).
+     */
+    async verifiedUnpostableAllowance() {
+        try {
+            const stamp = (await this.storage.getMetadata(UNPOSTABLE_STAMP_KEY));
+            if (!stamp || typeof stamp.nounCount !== 'number' || stamp.nounCount <= 0)
+                return 0;
+            if (Array.isArray(stamp.nounIds) && stamp.nounIds.length === stamp.nounCount) {
+                const getMeta = this.storage.getNounMetadata;
+                if (typeof getMeta !== 'function')
+                    return stamp.nounCount;
+                let stillUnpostable = 0;
+                for (const id of stamp.nounIds) {
+                    const md = await getMeta.call(this.storage, id).catch(() => undefined);
+                    if (md == null)
+                        stillUnpostable++;
+                }
+                return stillUnpostable;
+            }
+            prodLog.warn(`[NativeMetadataIndex] unpostable stamp is count-only ` +
+                `(${stamp.nounCount} > id cap) — the posted-count floor carries its ` +
+                `staleness until the next completed rebuild refreshes it.`);
+            return stamp.nounCount;
+        }
+        catch {
+            return 0;
+        }
+    }
     async detectDerivedStrand() {
         if (!this.lsmEngine || !this.lsmMetaDir)
             return;
@@ -1364,13 +1413,31 @@ export class MetadataIndexManager {
                     // smaller than the (1–2 entity) system skew is masked here and
                     // falls to the archive census above; the exact invariant (a
                     // persisted posted-count stamp) is CORTEX-BILLION-SCALE-SPINE work.
-                    if (posted < canonical) {
+                    //
+                    // UNPOSTABLE ALLOWANCE (the constant-52, CORTEX-RESTART-STRAND):
+                    // canonical rows with NO readable metadata cannot carry a
+                    // posting, and a completed rebuild PROVES which those are (each
+                    // verified by direct read) and stamps them. Without the
+                    // allowance the same cohort re-flags every boot and re-triggers
+                    // a pointless full heal forever. The stamp's ids are RE-VERIFIED
+                    // here (an id that has since gained metadata stops counting), so
+                    // the floor stays exact; beyond UNPOSTABLE_ID_CAP the stamp is
+                    // count-only and the allowance carries a bounded, logged
+                    // staleness caveat.
+                    const unpostable = await this.verifiedUnpostableAllowance();
+                    if (posted + unpostable < canonical) {
                         this.strandDetected = true;
                         prodLog.error(`[NativeMetadataIndex] STRAND: canonical holds ${canonical} ` +
-                            `entities but the index has postings for only ${posted} — ` +
-                            `${canonical - posted}+ entities are durable in canonical but ` +
-                            `UNQUERYABLE (lost postings). Reporting not-ready so the ` +
-                            `cold-open gate rebuilds from canonical.`);
+                            `entities but the index has postings for only ${posted}` +
+                            (unpostable > 0 ? ` (+${unpostable} verified-unpostable allowance)` : '') +
+                            ` — ${canonical - posted - unpostable}+ entities are durable in ` +
+                            `canonical but UNQUERYABLE (lost postings). Reporting not-ready ` +
+                            `so the cold-open gate rebuilds from canonical.`);
+                    }
+                    else if (unpostable > 0 && posted < canonical) {
+                        prodLog.info(`[NativeMetadataIndex] posted ${posted} < canonical ${canonical} is ` +
+                            `FULLY explained by ${unpostable} verified metadata-less canonical ` +
+                            `entities (stamped by the last completed rebuild) — no strand, no heal.`);
                     }
                 }
             }
@@ -2401,15 +2468,23 @@ export class MetadataIndexManager {
                 for (const t of Object.values(NounType)) {
                     posted += this.native.getEntityCountByType(t);
                 }
+                // Same verified-unpostable allowance as the strand detector — a
+                // metadata-less canonical row (proven by the last completed
+                // rebuild) cannot carry a posting and must not read as damage
+                // here either, or brainy's repairIndex loops the same heal the
+                // detector fix just broke.
+                const unpostable = await this.verifiedUnpostableAllowance();
+                const floor = posted + unpostable;
                 return {
                     name: 'posted-count-floor',
-                    holds: posted >= canonical,
-                    detail: posted >= canonical
-                        ? `posted ${posted} ≥ canonical ${canonical}`
+                    holds: floor >= canonical,
+                    detail: floor >= canonical
+                        ? `posted ${posted}${unpostable > 0 ? ` (+${unpostable} verified-unpostable)` : ''} ≥ canonical ${canonical}`
                         : `canonical holds ${canonical} entities but only ${posted} are ` +
-                            `posted — ${canonical - posted} durable-but-unqueryable`,
+                            `posted (${unpostable} verified-unpostable allowed) — ` +
+                            `${canonical - floor} durable-but-unqueryable`,
                     expected: canonical,
-                    actual: posted,
+                    actual: floor,
                     heal: 'rebuild',
                 };
             },
@@ -2904,11 +2979,11 @@ export class MetadataIndexManager {
                     'function';
             if (bulkCapable)
                 this.lsmEngine.setBulkLoad(true);
-            let totalNounsProcessed;
-            let totalVerbsProcessed;
+            let nounResult;
+            let verbResult;
             try {
-                totalNounsProcessed = await this.rebuildEntityMetadata('noun');
-                totalVerbsProcessed = await this.rebuildEntityMetadata('verb');
+                nounResult = await this.rebuildEntityMetadata('noun');
+                verbResult = await this.rebuildEntityMetadata('verb');
             }
             finally {
                 // Leaving bulk mode performs the walk's single durability point
@@ -2922,7 +2997,22 @@ export class MetadataIndexManager {
             this.isRebuilding = false;
             await this.flushRebuildDirty();
             await this.flush();
-            prodLog.info(`Metadata index rebuild completed! Processed ${totalNounsProcessed} nouns and ${totalVerbsProcessed} verbs`);
+            // Persist what this COMPLETED walk PROVED unpostable (each id
+            // verified by direct canonical read) so the next boot's strand
+            // detector uses the honest floor instead of re-flagging the same
+            // cohort forever. Refreshed on every completed rebuild; an empty
+            // set clears the stamp.
+            await this.storage.saveMetadata(UNPOSTABLE_STAMP_KEY, {
+                nounCount: nounResult.noMetadata,
+                nounIds: nounResult.noMetadataIds,
+                verbCount: verbResult.noMetadata,
+                verifiedAt: Date.now(),
+            });
+            prodLog.info(`Metadata index rebuild completed! Processed ${nounResult.processed} nouns and ` +
+                `${verbResult.processed} verbs` +
+                (nounResult.noMetadata > 0
+                    ? ` (${nounResult.noMetadata} canonical noun(s) verified metadata-less — stamped for the strand detector)`
+                    : ''));
             // A completed rebuild re-posted every canonical entity into a freshly
             // re-opened engine (reopenLsmEngineFresh wiped the stale shard set) —
             // any cold-open strand verdict is now satisfied.
@@ -2950,6 +3040,7 @@ export class MetadataIndexManager {
         let processed = 0;
         let sinceFlush = 0;
         let noMetadata = 0;
+        const noMetadataIds = [];
         // 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
@@ -3000,6 +3091,8 @@ export class MetadataIndexManager {
                 }
                 else {
                     noMetadata++;
+                    if (noMetadataIds.length < UNPOSTABLE_ID_CAP)
+                        noMetadataIds.push(it.id);
                 }
             }
             hasMore = page.hasMore;
@@ -3013,9 +3106,10 @@ export class MetadataIndexManager {
             prodLog.warn(`[NativeMetadataIndex] rebuild(${kind}): ${noMetadata} enumerated ` +
                 `entit${noMetadata === 1 ? 'y' : 'ies'} carried no canonical ` +
                 `metadata (verified by direct read) and were not indexed — ` +
-                `expected only for metadata-less legacy records.`);
+                `expected only for metadata-less legacy records. First ids: ` +
+                noMetadataIds.slice(0, 10).join(', '));
         }
-        return processed;
+        return { processed, noMetadata, noMetadataIds };
     }
     /**
      * Rebuild-path verify-read for a single entity's canonical metadata.

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.16";
+export declare const COR_VERSION = "3.0.17";
 //# 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.16';
+export const COR_VERSION = '3.0.17';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.16",
+  "version": "3.0.17",
   "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",