fix(8.0): close GA-blocking correctness gaps from the readiness audit

- Version-coupling cold-init: getBrainyVersion() returned a stale build-time
  default ('3.14.0') on the FIRST synchronous call — the one loadPlugins() makes
  to build context.version — because the package.json read was async. A native
  provider declaring a realistic `>=8.0.0` range was therefore rejected on cold
  init. version.ts now reads package.json synchronously (8.0 targets Node-like
  runtimes only); added a cold-init coupling regression with a `^8.0.0` plugin.
- No-silent-failures on the highest-fan-in read path: getNouns()/getVerbs()
  converted a storage read failure into a success-shaped empty page, which the
  cold-start rebuild then read as "store empty" and skipped the rebuild — booting
  a permanently-empty index with no signal (the same silent-failure class as the
  phantom bug). Both now re-throw a named BrainyError; the rebuild path re-throws
  read failures (fail loud) and records a queryable degraded state, surfaced via
  checkHealth(), for non-fatal rebuild hiccups.
- LSM SSTable leak: graph compaction wrote a merged SSTable but only dropped the
  old ones from the manifest, orphaning their payloads forever ("In production
  we'd add a cleanup mechanism"). Added StorageAdapter.deleteMetadata() and now
  reclaim each compacted-away SSTable.
- Documented the two headline methods add() and find() (the only undocumented
  public methods on the class).

Full gate green: build, unit 1512, integration 607.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/utils/version.ts

@@ -1,100 +1,85 @@
 /**
- * Version utilities for Brainy
+ * @module utils/version
+ * @description Resolves the running `@soulcraft/brainy` package version. Brainy 8.0
+ * targets Node-like runtimes only (Node.js, Bun, Deno — all expose `node:fs`), so the
+ * version is read **synchronously** from `package.json` on first call and cached.
+ *
+ * The synchronous read is load-bearing: `loadPlugins()` is the first step of `init()`
+ * and reads the version to drive the brainy↔provider version-coupling guard
+ * (`plugin.ts` → `pluginRangeSatisfies`). A deferred/async value would return a stale
+ * default on that first synchronous call and spuriously reject a correctly-matched
+ * native provider (e.g. cor 3.x declaring `>=8.0.0`). Reading synchronously removes
+ * that window entirely.
  */
 
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { isNode } from './environment.js'
 
-// Default version - this should be replaced at build time
-const DEFAULT_VERSION = '3.14.0'
+/**
+ * Last-resort sentinel, returned only if `package.json` cannot be read at all
+ * (a non-Node runtime, or a genuinely broken install). It is intentionally an
+ * "unknown" `0.0.0` rather than a plausible-looking release, so a real read
+ * failure can never masquerade as a valid version and silently satisfy a
+ * coupling range — it will fail loud instead.
+ */
+const UNKNOWN_VERSION = '0.0.0'
 
 let cachedVersion: string | null = null
-let versionPromise: Promise<string> | null = null
 
 /**
- * Load version from package.json in Node.js environment
+ * Synchronously read `version` from the package's own `package.json`. The path
+ * `../../package.json` resolves to the package root from both `src/utils/` (dev)
+ * and `dist/utils/` (published).
  */
-async function loadVersionFromPackageJson(): Promise<string> {
-  if (!isNode()) {
-    return DEFAULT_VERSION
-  }
-
+function readVersionSync(): string {
+  if (!isNode()) return UNKNOWN_VERSION
   try {
-    // Dynamic imports for Node.js modules - modern approach
-    const [{ readFileSync }, { join, dirname }, { fileURLToPath }] = await Promise.all([
-      import('node:fs'),
-      import('node:path'),
-      import('node:url')
-    ])
-
-    const __filename = fileURLToPath(import.meta.url)
-    const __dirname = dirname(__filename)
-    const packageJsonPath = join(__dirname, '../../package.json')
-
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
-    return packageJson.version || DEFAULT_VERSION
-  } catch (error) {
-    // Silently fall back to default version
-    return DEFAULT_VERSION
+    const here = dirname(fileURLToPath(import.meta.url))
+    const pkg = JSON.parse(readFileSync(join(here, '../../package.json'), 'utf8'))
+    return typeof pkg.version === 'string' && pkg.version.length > 0
+      ? pkg.version
+      : UNKNOWN_VERSION
+  } catch {
+    return UNKNOWN_VERSION
   }
 }
 
 /**
- * Get the current Brainy package version
- * In Node.js, attempts to read from package.json
- * In browser, returns the default version
- * @returns The current version string
+ * @description The running Brainy package version, read synchronously from
+ * `package.json` and cached. Correct on the **first** call — including the
+ * version-coupling check during `init()` — with no async warm-up.
+ * @returns The semver version string (e.g. `"8.0.0"`).
+ * @example
+ * const v = getBrainyVersion() // "8.0.0"
  */
 export function getBrainyVersion(): string {
-  if (cachedVersion) {
-    return cachedVersion
-  }
-
-  // In browser or if we need immediate response, return default
-  if (!isNode()) {
-    cachedVersion = DEFAULT_VERSION
-    return cachedVersion
-  }
-
-  // For Node.js, try to load synchronously first time
-  // This is a compromise for backward compatibility
-  if (!versionPromise) {
-    versionPromise = loadVersionFromPackageJson()
-    versionPromise.then(version => {
-      cachedVersion = version
-    })
-  }
-
-  // Return default while loading
-  return cachedVersion || DEFAULT_VERSION
+  if (cachedVersion === null) cachedVersion = readVersionSync()
+  return cachedVersion
 }
 
 /**
- * Get the current Brainy package version asynchronously
- * Guaranteed to attempt loading from package.json in Node.js
- * @returns Promise resolving to the current version string
+ * @description Async accessor retained for API compatibility. The version is
+ * resolved synchronously, so this returns the same value as
+ * {@link getBrainyVersion} — there is no longer any deferred state.
+ * @returns A promise resolving to the version string.
  */
 export async function getBrainyVersionAsync(): Promise<string> {
-  if (cachedVersion) {
-    return cachedVersion
-  }
-
-  if (!versionPromise) {
-    versionPromise = loadVersionFromPackageJson()
-  }
-
-  const version = await versionPromise
-  cachedVersion = version
-  return version
+  return getBrainyVersion()
 }
 
 /**
- * Get version information for augmentation metadata
- * @param service The service/augmentation name
- * @returns Version metadata object
+ * @description Build the version-metadata object stamped onto augmentation /
+ * provenance records.
+ * @param service - The augmentation or service name to record.
+ * @returns `{ augmentation, version }` carrying the current package version.
+ * @example
+ * getAugmentationVersion('aggregation') // { augmentation: 'aggregation', version: '8.0.0' }
  */
 export function getAugmentationVersion(service: string): { augmentation: string; version: string } {
   return {
     augmentation: service,
     version: getBrainyVersion()
   }
-}
+}