@soulcraft/cor 3.0.14 → 3.0.16

package/dist/utils/derivedFamilies.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module utils/derivedFamilies
+ * @description ADR-004 §7 — cor's registered-blob family declarations
+ * (adopted 2026-07-13). Each provider declares the artifact families it
+ * owns through brainy ≥8.3.0's `registerDerivedFamily` (feature-detected;
+ * inert on older adapters). Once declared, the storage layer REFUSES to
+ * delete a member (`ProtectedArtifactError` — an in-process GC/sweeper is
+ * structurally incapable of removing a load-bearing file), and
+ * `checkDerivedFamiliesPresent` names any missing-on-open member (the
+ * external-deleter catch).
+ *
+ * Scope note (deliberate split, per §7): declarations cover
+ * KEY-ADDRESSABLE artifacts — members resolve through the same adapter
+ * key→path function on both sides, so consistency is by construction.
+ * Path-level siblings the native layer writes directly (the vector
+ * base's `.slotmap`/`.slotrev` sidecars) are outside the key space; their
+ * set-coherence is cor's own `familygen` stamp (the §7 atomic set-swap),
+ * not the storage contract. Growing sets use `namespace: true` prefixes.
+ *
+ * Registration is idempotent (upsert by family name) and runs on every
+ * open. A registration failure is LOUD but never blocks an open — the
+ * contract is protective, not load-bearing.
+ */
+import type { DerivedFamilyDeclaration } from '@soulcraft/brainy';
+/**
+ * Declare families on the adapter when it supports the contract. Never
+ * throws; failures are loud. Returns how many were registered (0 when the
+ * adapter predates the contract — callers may log that once at debug).
+ */
+export declare function declareDerivedFamilies(storage: unknown, families: DerivedFamilyDeclaration[]): Promise<number>;
+/** The vector index's key-addressable families. */
+export declare const VECTOR_FAMILIES: DerivedFamilyDeclaration[];
+/** The metadata LSM's families (engine dir + SSTables share the key prefix). */
+export declare const METADATA_FAMILIES: DerivedFamilyDeclaration[];
+/** The column store's family (fully key-addressable — API delete-refusal bites here). */
+export declare const COLUMN_FAMILIES: DerivedFamilyDeclaration[];
+/** The graph index's families (LSM SSTables + verb namespace stores). */
+export declare const GRAPH_FAMILIES: DerivedFamilyDeclaration[];
+/**
+ * Owner-sanctioned retirement window (the pattern brainy's
+ * ProtectedArtifactError names): unregister the family, run the owner's
+ * legitimate delete work, re-register in a finally. The unprotected
+ * window is small and self-healing — every provider re-declares its
+ * families on init, so even a crash inside the window is repaired at the
+ * next open. On adapters without the contract, just runs `fn`.
+ */
+export declare function withFamilyRetirement<T>(storage: unknown, family: DerivedFamilyDeclaration, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=derivedFamilies.d.ts.map

package/dist/utils/derivedFamilies.js

@@ -0,0 +1,128 @@
+/**
+ * @module utils/derivedFamilies
+ * @description ADR-004 §7 — cor's registered-blob family declarations
+ * (adopted 2026-07-13). Each provider declares the artifact families it
+ * owns through brainy ≥8.3.0's `registerDerivedFamily` (feature-detected;
+ * inert on older adapters). Once declared, the storage layer REFUSES to
+ * delete a member (`ProtectedArtifactError` — an in-process GC/sweeper is
+ * structurally incapable of removing a load-bearing file), and
+ * `checkDerivedFamiliesPresent` names any missing-on-open member (the
+ * external-deleter catch).
+ *
+ * Scope note (deliberate split, per §7): declarations cover
+ * KEY-ADDRESSABLE artifacts — members resolve through the same adapter
+ * key→path function on both sides, so consistency is by construction.
+ * Path-level siblings the native layer writes directly (the vector
+ * base's `.slotmap`/`.slotrev` sidecars) are outside the key space; their
+ * set-coherence is cor's own `familygen` stamp (the §7 atomic set-swap),
+ * not the storage contract. Growing sets use `namespace: true` prefixes.
+ *
+ * Registration is idempotent (upsert by family name) and runs on every
+ * open. A registration failure is LOUD but never blocks an open — the
+ * contract is protective, not load-bearing.
+ */
+import { prodLog } from '@soulcraft/brainy/internals';
+/**
+ * Declare families on the adapter when it supports the contract. Never
+ * throws; failures are loud. Returns how many were registered (0 when the
+ * adapter predates the contract — callers may log that once at debug).
+ */
+export async function declareDerivedFamilies(storage, families) {
+    const s = storage;
+    if (typeof s?.registerDerivedFamily !== 'function')
+        return 0;
+    let registered = 0;
+    for (const family of families) {
+        try {
+            await s.registerDerivedFamily(family);
+            registered++;
+        }
+        catch (error) {
+            prodLog.error(`[cor] registerDerivedFamily('${family.name}') FAILED — its members ` +
+                `are NOT delete-protected this session (opens are unaffected):`, error);
+        }
+    }
+    return registered;
+}
+/** The vector index's key-addressable families. */
+export const VECTOR_FAMILIES = [
+    {
+        name: 'vector-base',
+        members: ['_system/vector-index/main.dkann'],
+        rebuildable: true,
+    },
+    {
+        name: 'vector-segments',
+        members: ['_system/vector-index/seg-'],
+        namespace: true,
+        rebuildable: true,
+    },
+];
+/** The metadata LSM's families (engine dir + SSTables share the key prefix). */
+export const METADATA_FAMILIES = [
+    {
+        name: 'metadata-lsm',
+        members: ['_metadata'],
+        namespace: true,
+        rebuildable: true,
+    },
+    {
+        name: 'id-mapper',
+        members: ['_id_mapper/'],
+        namespace: true,
+        rebuildable: true,
+    },
+];
+/** The column store's family (fully key-addressable — API delete-refusal bites here). */
+export const COLUMN_FAMILIES = [
+    {
+        name: 'column-index',
+        members: ['_column_index/'],
+        namespace: true,
+        rebuildable: true,
+    },
+];
+/** The graph index's families (LSM SSTables + verb namespace stores). */
+export const GRAPH_FAMILIES = [
+    {
+        name: 'graph-lsm',
+        members: ['graph-lsm/'],
+        namespace: true,
+        rebuildable: true,
+    },
+    {
+        name: 'graph-verb-namespace',
+        members: ['_graph_verb_ns/'],
+        namespace: true,
+        rebuildable: true,
+    },
+];
+/**
+ * Owner-sanctioned retirement window (the pattern brainy's
+ * ProtectedArtifactError names): unregister the family, run the owner's
+ * legitimate delete work, re-register in a finally. The unprotected
+ * window is small and self-healing — every provider re-declares its
+ * families on init, so even a crash inside the window is repaired at the
+ * next open. On adapters without the contract, just runs `fn`.
+ */
+export async function withFamilyRetirement(storage, family, fn) {
+    const s = storage;
+    if (typeof s?.unregisterDerivedFamily !== 'function' ||
+        typeof s?.registerDerivedFamily !== 'function') {
+        return fn();
+    }
+    await s.unregisterDerivedFamily(family.name);
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            await s.registerDerivedFamily(family);
+        }
+        catch (error) {
+            prodLog.error(`[cor] re-register of family '${family.name}' after retirement ` +
+                `FAILED — protection resumes at the next open:`, error);
+        }
+    }
+}
+//# sourceMappingURL=derivedFamilies.js.map

package/dist/utils/invariantReport.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module utils/invariantReport
+ * @description Shared composer for the ADR-004 §6 `validateInvariants()`
+ * hook (adopted 2026-07-13, decision `adr-004-write-index-spine-adoption`).
+ * Every cor provider builds its report through this so the contract holds
+ * uniformly: the hook NEVER throws (a thrown check is surfaced as a failing
+ * invariant naming the throw — never an exception, never swallowed), stays
+ * bounded (checks are residency + O(1) counts only; the composer measures
+ * and reports duration), and failures carry named, numbered detail.
+ *
+ * Types are imported from brainy 8.3.0's published surface so both engines
+ * share one wire shape (`ProviderInvariantReport` / `InvariantResult` /
+ * `InvariantHeal` — brainy's `validateIndexConsistency` feature-detects the
+ * hook and aggregates these verbatim; `repairIndex` maps `heal: 'rebuild'`
+ * to the provider's own rebuild).
+ */
+import type { InvariantResult, ProviderInvariantReport } from '@soulcraft/brainy';
+/** One invariant check: returns its result, sync or async. A throw is a
+ * contract violation the composer converts into a failing invariant. */
+export type InvariantCheck = () => InvariantResult | Promise<InvariantResult>;
+/**
+ * Run every check, never throw, stamp timing. A check that throws becomes
+ * `holds: false` with `heal: 'none'` and detail naming the throw — the
+ * never-throws contract surfaced as unhealthy data rather than an exception
+ * (and `heal: 'none'` so a flaky probe can never trigger a spurious
+ * rebuild; visibility without overreaction).
+ */
+export declare function composeInvariantReport(provider: string, serving: () => boolean, checks: InvariantCheck[]): Promise<ProviderInvariantReport>;
+//# sourceMappingURL=invariantReport.d.ts.map

package/dist/utils/invariantReport.js

@@ -0,0 +1,62 @@
+/**
+ * @module utils/invariantReport
+ * @description Shared composer for the ADR-004 §6 `validateInvariants()`
+ * hook (adopted 2026-07-13, decision `adr-004-write-index-spine-adoption`).
+ * Every cor provider builds its report through this so the contract holds
+ * uniformly: the hook NEVER throws (a thrown check is surfaced as a failing
+ * invariant naming the throw — never an exception, never swallowed), stays
+ * bounded (checks are residency + O(1) counts only; the composer measures
+ * and reports duration), and failures carry named, numbered detail.
+ *
+ * Types are imported from brainy 8.3.0's published surface so both engines
+ * share one wire shape (`ProviderInvariantReport` / `InvariantResult` /
+ * `InvariantHeal` — brainy's `validateIndexConsistency` feature-detects the
+ * hook and aggregates these verbatim; `repairIndex` maps `heal: 'rebuild'`
+ * to the provider's own rebuild).
+ */
+/**
+ * Run every check, never throw, stamp timing. A check that throws becomes
+ * `holds: false` with `heal: 'none'` and detail naming the throw — the
+ * never-throws contract surfaced as unhealthy data rather than an exception
+ * (and `heal: 'none'` so a flaky probe can never trigger a spurious
+ * rebuild; visibility without overreaction).
+ */
+export async function composeInvariantReport(provider, serving, checks) {
+    const startedAt = Date.now();
+    const invariants = [];
+    for (const check of checks) {
+        try {
+            invariants.push(await check());
+        }
+        catch (error) {
+            invariants.push({
+                name: 'check-integrity',
+                holds: false,
+                detail: `an invariant check THREW (contract violation — checks must ` +
+                    `return failures as data): ${String(error)}`,
+                heal: 'none',
+            });
+        }
+    }
+    let servingNow = false;
+    try {
+        servingNow = serving();
+    }
+    catch (error) {
+        invariants.push({
+            name: 'serving-probe',
+            holds: false,
+            detail: `isReady() itself threw: ${String(error)}`,
+            heal: 'none',
+        });
+    }
+    return {
+        provider,
+        healthy: invariants.every((i) => i.holds),
+        serving: servingNow,
+        invariants,
+        checkedAt: startedAt,
+        durationMs: Date.now() - startedAt,
+    };
+}
+//# sourceMappingURL=invariantReport.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.16";
+//# 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.16';
+//# sourceMappingURL=version.js.map

package/native/index.d.ts

@@ -364,7 +364,6 @@ export declare class NativeColumnStore {
   distinctValues(field: string): Array<string>
 }
 
-/** Napi-exposed DiskANN index. */
 export declare class NativeDiskAnn {
   /** Construct via static factories. */
   constructor()
@@ -1751,6 +1750,20 @@ export declare class NativeMetadataIndex {
    * brains; preferred by brainy 8.0 consumers.
    */
   uuidToIntBig(uuid: string): bigint | null
+  /**
+   * Resolve an entity's integer id, ASSIGNING a fresh one through the
+   * canonical allocator when unmapped — the same allocator
+   * `add_to_index` uses, so a later `add_to_index` for this UUID
+   * reuses the id and the assignment persists through the mapper's
+   * own durability (delta log). Exists for the boot-heal vector
+   * rebuild (CORTEX-RESTART-STRAND, 2026-07-13): a canonical entity
+   * whose index ops were lost (canonical committed, postings absent)
+   * has no int at cold-rebuild time — the rebuild must be able to
+   * mint one instead of aborting the whole heal. The entity's missing
+   * METADATA postings stay visible to `validateInvariants()`'s
+   * posted-count-floor check; this method never masks that gap.
+   */
+  getOrAssignInt(uuid: string): bigint
   /**
    * Resolve a UUID from an entity's integer id. Backs `getIdMapper().getUuid`
    * for the `orderBy` path. O(1).
@@ -2614,6 +2627,15 @@ export declare function euclideanDistance(a: Array<number>, b: Array<number>): n
 /** Batch euclidean distance: compute distances from a query to multiple vectors. */
 export declare function euclideanDistanceBatch(query: Array<number>, vectors: Array<Array<number>>): Array<number>
 
+/**
+ * Napi-exposed DiskANN index.
+ * ADR-004 §7 capability probe: TRUE on binaries whose publish path
+ * writes the `main.familygen` stamp and swaps the vector family
+ * atomically (3.0.16+). TS code and the test suite gate stamp-dependent
+ * behavior on this instead of guessing from version strings.
+ */
+export declare function familygenSupported(): boolean
+
 /**
  * Outcome of raising the open-file limit. Field names cross to JS as
  * camelCase (`softBefore`, `softAfter`, `hard`, `raised`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.14",
+  "version": "3.0.16",
   "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.2.6",
+    "@soulcraft/brainy": "8.3.0",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",