Merge branch 'worktree-agent-ad3aff0dffd17a6eb'

src/brainy.ts

@@ -742,6 +742,15 @@ export class Brainy<T = any> implements BrainyInterface<T> {
   private _pendingEmbedIds = new Set<string>()
   private _embedWorkerFlight: Promise<void> | null = null
 
+  // OPEN-PATH FIX: the background embedding-engine warm kicked off (never
+  // awaited) by `performInit()` when `eagerEmbeddings` resolves true. Stored
+  // for observability only — `embed()`/`embeddingManager.embed()` already
+  // await the engine's OWN singleton init promise internally, so nothing
+  // needs to explicitly await this field for correctness. Never rejects on
+  // its own: a `.catch` narrates the failure and swallows it so a failed
+  // warm never surfaces as an unhandled rejection.
+  private _embeddingWarmPromise: Promise<void> | null = null
+
   /** The stored log-authority switch, read once at open (default: tree). */
   private _logAuthority: LogAuthorityRecord = { authority: 'tree' }
   // A failed walk latches its error: retries within the cooldown rethrow it
@@ -1079,6 +1088,23 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       configureLogger({ level: LogLevel.DEBUG })  // Enable verbose logging
     }
 
+    // OPEN-PATH NARRATION: lightweight phase timing across the five
+    // named stretches of init — storage init / generation-store open+fold /
+    // index init+gate / VFS bootstrap / embedding-warm-started. Each
+    // `markPhase()` call records elapsed ms SINCE THE PREVIOUS checkpoint,
+    // so the buckets always sum to the pre-integration/warmOnOpen total.
+    // Silent under 2s; one `prodLog.warn` line naming every phase's ms
+    // above it, so the operator's next restart storm names its own slow
+    // phase instead of re-deriving it from a stack of raw timestamps.
+    const initStart = Date.now()
+    let lastPhaseCheckpoint = initStart
+    const phaseTimingsMs: Record<string, number> = {}
+    const markPhase = (name: string): void => {
+      const now = Date.now()
+      phaseTimingsMs[name] = now - lastPhaseCheckpoint
+      lastPhaseCheckpoint = now
+    }
+
     try {
       // Auto-detect and activate plugins BEFORE storage setup
       // so plugin-provided storage factories (e.g., filesystem override from cor) are available
@@ -1150,6 +1176,12 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         }
       }
 
+      // PHASE 1 of 5 — "storage init": plugin/legacy-layout bootstrap,
+      // storage adapter construction+init, the OS-limit check, and the
+      // writer-lock claim, all folded into one bucket (everything above this
+      // line since performInit started).
+      markPhase('storage-init')
+
       // 8.0 generational MVCC: open the record layer BEFORE any index is
       // created or loaded. Crash recovery may rewrite canonical entity files
       // (restoring before-images of an uncommitted transaction), and every
@@ -1224,6 +1256,12 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         await this.createMigrationBackupIfNeeded()
       }
 
+      // PHASE 2 of 5 — "generation-store open+fold": GenerationStore
+      // construction+open (crash-recovery replay/rollback fold), the
+      // derived-family registration, the fact-scan seam, the entity-tree
+      // stamp check, the brain-format handshake, and the pre-upgrade backup.
+      markPhase('generation-store-open-fold')
+
       // Provider: embeddings (reassign embedder if plugin provides one)
       const embeddingProvider = this.pluginRegistry.getProvider<EmbeddingFunction>('embeddings')
       if (embeddingProvider) {
@@ -1475,6 +1513,14 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       // Check for pending data migrations
       await this.checkMigrations()
 
+      // PHASE 3 of 5 — "index init+gate": provider wiring (embeddings,
+      // cache, roaring, msgpack, sort:topK, distance), HNSW/metadata/graph
+      // index construction, the eager cold-load, id-resolver + connections-
+      // codec wiring, crash-recovery index rebuild, the replay-gap check,
+      // legacy VFS blob adoption, blob-history backfill, and the
+      // rebuildIndexesIfNeeded() gate + migration check.
+      markPhase('index-init-gate')
+
       // Register shutdown hooks for graceful count flushing (once globally)
       if (!Brainy.shutdownHooksRegisteredGlobally) {
         this.registerShutdownHooks()
@@ -1626,15 +1672,40 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         }
       }
 
-      // Eager embedding initialization.
+      // PHASE 4 of 5 — "VFS bootstrap": shutdown-hook registration, blob
+      // storage init, the provider-summary log, flipping `initialized`,
+      // the migration-lock wait, VFS construction+init, flipping generation
+      // stamping active, the log-authority adopt/oracle check, and
+      // pending-embed crash recovery.
+      markPhase('vfs-bootstrap')
+
+      // Eager embedding initialization — BACKGROUND WARM (open-path fix).
       //
-      // Adaptive default (8.0): the WASM embedding engine eagerly initializes
+      // Adaptive default (8.0): the WASM embedding engine eagerly WARMS
       // during init() WHENEVER it is the active embedder — i.e. no native
       // 'embeddings' provider has taken over — and the instance is a writer
       // (not reader-mode) outside of unit tests. The WASM module (≈93MB with
-      // the embedded model) takes 90-140s to compile on throttled CPUs; paying
-      // that during boot rather than on the first embed()-driven call is the
-      // right default for the overwhelmingly common single-process server.
+      // the embedded model) takes 90-140s to compile on throttled CPUs.
+      //
+      // Historically this AWAITED `embeddingManager.init()` INLINE, so every
+      // writer's open() blocked on the compile — N concurrent opens all
+      // queued on the ONE process-global singleton (an ~80x contention
+      // multiplier measured in a production restart storm: 90,017ms busy vs
+      // 1,117ms quiet). The engine only needs to be ready before the FIRST
+      // REAL embed() call, not before init() returns, so this now only
+      // STARTS the warm and moves on — init() never waits for it.
+      //
+      // No double-await needed for correctness: `this.embed()` (~line 15420)
+      // delegates to `this.embedder`, which for the default engine is
+      // `embeddingManager.getEmbeddingFunction()` → `embeddingManager.embed()`
+      // (src/embeddings/EmbeddingManager.ts). That method calls `await
+      // this.init()` FIRST, and `init()` itself serializes every concurrent
+      // caller onto ONE shared `globalInitPromise` — so the first real
+      // embed() automatically waits for whichever finishes first: this
+      // background warm (if still running) or a fresh init() (if the warm
+      // hasn't reached this code yet, e.g. `eagerEmbeddings: false`).
+      // Verified by reading both call sites; `_embeddingWarmPromise` below
+      // is stored for observability only, never re-awaited by embed().
       //
       // Skipped automatically when:
       //   - a native 'embeddings' provider is registered (it owns embeddings;
@@ -1642,8 +1713,8 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       //   - reader-mode (readers don't embed — they query existing vectors),
       //   - unit-test mode (tests must stay fast and use the mock embedder).
       //
-      // `eagerEmbeddings: false` is the explicit override to force lazy init
-      // (first-embed) even when this instance is the active embedder.
+      // `eagerEmbeddings: false` keeps meaning "no warm at all" — fully lazy,
+      // the first embed() call pays the full cost inline, same as before.
       const isUnitTestMode = isDeterministicEmbedMode()
       const eager = this.config.eagerEmbeddings ?? true
       if (
@@ -1652,9 +1723,45 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         this.config.mode !== 'reader' &&
         !isUnitTestMode
       ) {
-        console.log('Eager embedding initialization enabled...')
-        await embeddingManager.init()
-        console.log('Embedding engine ready')
+        const warmStart = Date.now()
+        console.log('Background embedding-engine warm started (init() does not wait for it)...')
+        this._embeddingWarmPromise = embeddingManager
+          .init()
+          .then(() => {
+            prodLog.info(
+              `[Brainy] background embedding-engine warm complete in ${Date.now() - warmStart}ms`
+            )
+          })
+          .catch((err) => {
+            // Loud, never silent: a warm that fails to compile must be
+            // heard NOW, not discovered as a mystery latency spike on
+            // whichever request happens to trigger the first real embed().
+            // That first embed() call still retries init() itself (the
+            // singleton promise contract above) and surfaces its own typed
+            // error to its caller — this is the immediate, background echo.
+            prodLog.warn(
+              `[Brainy] background embedding-engine warm FAILED: ` +
+                `${(err as Error).message} — the first embed() call will retry ` +
+                `initialization and surface the error there`
+            )
+          })
+      }
+
+      // PHASE 5 of 5 — "embedding-warm-started": just the synchronous cost
+      // of kicking off the background warm above (the warm's own compile
+      // time is NOT included — that's the whole point of backgrounding it).
+      markPhase('embedding-warm-started')
+      {
+        const totalOpenMs = Date.now() - initStart
+        if (totalOpenMs > 2000) {
+          const phaseList = Object.entries(phaseTimingsMs)
+            .map(([name, ms]) => `${name}=${ms}ms`)
+            .join(', ')
+          prodLog.warn(
+            `[Brainy] slow open: ${totalOpenMs}ms total (${phaseList}) — see the ` +
+              `phase breakdown above to find which one to investigate first`
+          )
+        }
       }
 
       // Integration Hub initialization
@@ -3469,11 +3576,20 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       // new `data`); otherwise new `data` re-embeds; otherwise the existing
       // vector is kept. Any vector change re-indexes HNSW below.
       let vector = existing.vector
+      // 'data' is a real new value whenever it's not null/undefined — an
+      // empty string ('') is legitimate content (e.g. truncating a file to
+      // empty via overwrite), matching validateUpdateParams's absent-vs-empty
+      // distinction. Using `Boolean(params.data)` here would treat '' as "no
+      // new data", silently skipping BOTH the deferred marker and the eager
+      // re-embed below — a stale vector left behind with no path to ever
+      // correct itself (a quiet loss, not the deferred-but-eventually-
+      // correct flicker the deferEmbedding contract promises).
+      const hasNewData = params.data !== undefined && params.data !== null
       // MT5 deferred re-embedding: the OLD vector keeps serving semantic
       // search — stale-but-present, never absent (the flicker law) — until
       // the background worker embeds the new data and swaps it atomically.
       const deferringEmbed =
-        params.deferEmbedding === true && Boolean(params.data) && !params.vector
+        params.deferEmbedding === true && hasNewData && !params.vector
       if (params.vector) {
         if (this.dimensions && params.vector.length !== this.dimensions) {
           throw new Error(
@@ -3481,13 +3597,13 @@ export class Brainy<T = any> implements BrainyInterface<T> {
           )
         }
         vector = params.vector
-      } else if (params.data && !deferringEmbed) {
+      } else if (hasNewData && !deferringEmbed) {
         vector = await this.embed(params.data)
       }
       // A deferred data change does NOT reindex now (the vector is unchanged;
       // the worker's atomic swap carries the real reindex later).
       const needsReindexing = Boolean(
-        (params.data && !deferringEmbed) || params.type || params.vector
+        (hasNewData && !deferringEmbed) || params.type || params.vector
       )
 
       // Always update the noun with new metadata
@@ -10495,6 +10611,11 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     // Resolve the updated vector — mirror of update(): an explicit `vector`
     // always wins, new `data` re-embeds, otherwise the existing vector is
     // kept. Any vector change re-indexes HNSW below.
+    // 'data' is present whenever it's not null/undefined — '' is real
+    // content (see the identical hasNewData in update()); a plain truthy
+    // check would silently skip re-embedding an emptied value and leave a
+    // stale vector with no path to ever correct itself.
+    const hasNewData = params.data !== undefined && params.data !== null
     let vector = existing.vector
     if (params.vector) {
       if (this.dimensions && params.vector.length !== this.dimensions) {
@@ -10503,10 +10624,10 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         )
       }
       vector = params.vector
-    } else if (params.data) {
+    } else if (hasNewData) {
       vector = await this.embed(params.data)
     }
-    const needsReindexing = Boolean(params.data || params.type || params.vector)
+    const needsReindexing = Boolean(hasNewData || params.type || params.vector)
 
     const newMetadata =
       params.merge !== false
@@ -15826,6 +15947,25 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     return embeddingManager.isInitialized()
   }
 
+  /**
+   * Whether the process-global WASM embedding engine (all-MiniLM-L6-v2,
+   * fixed 384-dim output, ≈93MB with the bundled model, 90-140s cold compile
+   * on throttled CPUs) is this instance's active embedder — `false` when a
+   * plugin has replaced it via the `'embeddings'` provider key. A native
+   * provider has no such cold-start cost and may use a different output
+   * dimension, so it is never worth avoiding.
+   *
+   * Used by init-path bootstrap writes (the VFS root — see
+   * `VirtualFileSystem.doInitializeRoot()`) to decide whether embedding a
+   * value during `init()` risks paying the WASM engine's cold compile.
+   *
+   * @returns true when the default WASM engine is active (no native
+   *   `'embeddings'` provider registered).
+   */
+  usesDefaultWasmEmbedder(): boolean {
+    return !this.pluginRegistry.hasProvider('embeddings')
+  }
+
   /**
    * Setup embedder
    */

src/storage/adapters/fileSystemStorage.ts

@@ -239,38 +239,54 @@ export class FileSystemStorage extends BaseStorage {
 
       // Finish any restore interrupted by a crash (resume the staged swap, or
       // discard an uncommitted staging area) BEFORE counts/derived state load,
-      // so the rest of startup sees the completed store.
+      // so the rest of startup sees the completed store. ORDER-DEPENDENT:
+      // `swapStagedRestoreIn()` reads `fs.readdir(rootDir)` and then
+      // removes/renames rootDir's own TOP-LEVEL entries to place the staged
+      // copy — racing that against the directory-creation batch below (which
+      // also touches rootDir's children) could see a half-created directory
+      // mid-swap or a mkdir racing a concurrent rm/rename on the same path.
+      // Stays strictly sequential, never folded into the OPEN-PATH batch.
       await this.completeInterruptedRestore()
 
-      // Create the nouns directory if it doesn't exist
-      await this.ensureDirectoryExists(this.nounsDir)
+      // OPEN-PATH FIX: the remaining bootstrap directories are mutually
+      // independent — each is its own subtree under rootDir, and
+      // `fs.mkdir(dir, { recursive: true })` creates every intermediate
+      // segment of ITS OWN path in one call, so it never depends on any
+      // sibling here existing first. Nothing between here and
+      // `initializeCounts()` reads any of them, so batching collapses what
+      // was up to 8 sequential mkdir round-trips (each a real syscall+await)
+      // into one wave — this is what serialized an N-writer restart storm on
+      // filesystem I/O it never structurally needed. `initializeCounts()`
+      // right after DOES depend on `systemDir` (which the batch creates), so
+      // it stays outside, awaited only once every directory has landed.
+      await Promise.all([
+        // Create the nouns directory if it doesn't exist
+        this.ensureDirectoryExists(this.nounsDir),
+        // Create the verbs directory if it doesn't exist
+        this.ensureDirectoryExists(this.verbsDir),
+        // Create the metadata directory if it doesn't exist
+        this.ensureDirectoryExists(this.metadataDir),
+        // Create the noun metadata directory if it doesn't exist
+        this.ensureDirectoryExists(this.nounMetadataDir),
+        // Create the verb metadata directory if it doesn't exist
+        this.ensureDirectoryExists(this.verbMetadataDir),
+        // Create both directories for backward compatibility
+        this.ensureDirectoryExists(this.systemDir),
+        // Only create legacy directory if it exists (don't create new legacy
+        // dirs) — a read-then-maybe-write, but on its own subtree, so it's
+        // still independent of every other entry in this batch.
+        (async () => {
+          if (await this.directoryExists(this.indexDir)) {
+            await this.ensureDirectoryExists(this.indexDir)
+          }
+        })(),
+        // Create the locks directory if it doesn't exist
+        this.ensureDirectoryExists(this.lockDir),
+        // Create the binary blobs directory if it doesn't exist
+        this.ensureDirectoryExists(this.blobsDir)
+      ])
 
-      // Create the verbs directory if it doesn't exist
-      await this.ensureDirectoryExists(this.verbsDir)
-
-      // Create the metadata directory if it doesn't exist
-      await this.ensureDirectoryExists(this.metadataDir)
-
-      // Create the noun metadata directory if it doesn't exist
-      await this.ensureDirectoryExists(this.nounMetadataDir)
-
-      // Create the verb metadata directory if it doesn't exist
-      await this.ensureDirectoryExists(this.verbMetadataDir)
-
-      // Create both directories for backward compatibility
-      await this.ensureDirectoryExists(this.systemDir)
-      // Only create legacy directory if it exists (don't create new legacy dirs)
-      if (await this.directoryExists(this.indexDir)) {
-        await this.ensureDirectoryExists(this.indexDir)
-      }
-
-      // Create the locks directory if it doesn't exist
-      await this.ensureDirectoryExists(this.lockDir)
-
-      // Create the binary blobs directory if it doesn't exist
-      await this.ensureDirectoryExists(this.blobsDir)
-
-      // Initialize count management
+      // Initialize count management — depends on systemDir, created above.
       this.countsFilePath = path.join(this.systemDir, 'counts.json')
       await this.initializeCounts()
 

src/types/brainy.types.ts

@@ -1983,25 +1983,32 @@ export interface BrainyConfig {
   reservedQueryMemory?: number     // Memory reserved for queries in bytes (e.g., 1073741824 = 1GB)
 
   /**
-   * Controls when the WASM embedding engine is initialized.
+   * Controls whether `init()` starts a BACKGROUND warm of the WASM embedding
+   * engine.
    *
-   * **Adaptive default (8.0):** when omitted, the engine eagerly initializes
-   * during `init()` whenever the WASM embedder is the *active* one — i.e. no
-   * native `'embeddings'` provider is registered — and this instance is a
-   * writer (not `mode: 'reader'`) running outside unit tests. The WASM module
-   * (≈93MB with the embedded model) takes 90-140s to compile on throttled
-   * CPUs, so paying that during boot rather than on the first `embed()`-driven
-   * call is the right default for a single-process server.
+   * **Adaptive default (8.0, background since the open-path fix):** when
+   * omitted, `init()` STARTS a background warm of the engine whenever the
+   * WASM embedder is the *active* one — i.e. no native `'embeddings'`
+   * provider is registered — and this instance is a writer (not
+   * `mode: 'reader'`) running outside unit tests. The WASM module (≈93MB with
+   * the embedded model) takes 90-140s to compile on throttled CPUs — but
+   * `init()` never awaits that compile. It only starts it, so N concurrent
+   * opens no longer serialize on the one process-global engine singleton.
+   * The first `embed()` call then waits for whichever finishes first: the
+   * background warm (if still running) or its own fresh init (if the warm
+   * never started, e.g. `eagerEmbeddings: false`) — both paths converge on
+   * the SAME shared promise inside the engine singleton, so the vector is
+   * always correct; only the timing of who pays the wait differs.
    *
    * The adaptive path skips itself automatically when a native embeddings
    * provider owns embeddings, in reader-mode (readers query existing vectors
    * and never embed), and in unit-test mode (kept fast via the mock embedder).
    *
-   * - `true` — force eager init during `init()` (the adaptive default already
-   *   does this for the active-embedder writer case; set it explicitly to be
-   *   unambiguous).
-   * - `false` — explicit override to force lazy init (first `embed()` call)
-   *   even when this instance is the active embedder.
+   * - `true` — force the background warm to start during `init()` (the
+   *   adaptive default already does this for the active-embedder writer
+   *   case; set it explicitly to be unambiguous).
+   * - `false` — no warm at all. Fully lazy: the first `embed()` call pays the
+   *   full cold-compile cost inline, on whichever request triggers it.
    */
   eagerEmbeddings?: boolean
 

src/utils/paramValidation.ts

@@ -540,6 +540,11 @@ function rejectForgedSystemKeys(metadata: Record<string, unknown> | undefined, s
 
 export function validateAddParams(params: AddParams): void {
   rejectForgedSystemKeys(params.metadata as Record<string, unknown> | undefined, 'add()')
+  // 'data' is ABSENT only when null/undefined — an empty string ('') is real
+  // content (a legitimate empty file's first write) and must not be treated
+  // as missing. Falsy-but-present values (0, false, '') all count as present;
+  // only the true "nothing was given" case is absent.
+  const hasData = params.data !== undefined && params.data !== null
   // MT5 deferred embedding: an explicit vector has nothing to defer, and a
   // deferral without data has nothing to embed — both are caller bugs that
   // must refuse with the fix, never be silently reinterpreted.
@@ -550,14 +555,14 @@ export function validateAddParams(params: AddParams): void {
           `the vector is already computed; drop one of the two.`
       )
     }
-    if (!params.data) {
+    if (!hasData) {
       throw new Error(
         `add(): deferEmbedding requires 'data' (the content the background worker will embed).`
       )
     }
   }
   // Universal truth: must have data or vector
-  if (!params.data && !params.vector) {
+  if (!hasData && !params.vector) {
     throw new Error(
       `Invalid add() parameters: Missing required field 'data'\n` +
       `\nReceived: ${JSON.stringify({
@@ -597,6 +602,10 @@ export function validateAddParams(params: AddParams): void {
  */
 export function validateUpdateParams(params: UpdateParams): void {
   rejectForgedSystemKeys(params.metadata as Record<string, unknown> | undefined, 'update()')
+  // Same absent-vs-empty distinction as validateAddParams: '' is a real new
+  // value (e.g. truncating a file to empty content via overwrite), only
+  // null/undefined means "no new data was given".
+  const hasData = params.data !== undefined && params.data !== null
   if ((params as UpdateParams & { deferEmbedding?: boolean }).deferEmbedding === true) {
     if (params.vector) {
       throw new Error(
@@ -604,7 +613,7 @@ export function validateUpdateParams(params: UpdateParams): void {
           `the vector is already computed; drop one of the two.`
       )
     }
-    if (!params.data) {
+    if (!hasData) {
       throw new Error(
         `update(): deferEmbedding requires new 'data' — without a data change there is nothing to re-embed.`
       )
@@ -614,10 +623,10 @@ export function validateUpdateParams(params: UpdateParams): void {
   if (!params.id) {
     throw new Error('id is required for update')
   }
-  
+
   // Universal truth: must update something
   if (
-    !params.data &&
+    !hasData &&
     !params.metadata &&
     !params.type &&
     !params.vector &&

src/vfs/VirtualFileSystem.ts

@@ -89,6 +89,16 @@ export class VirtualFileSystem implements IVirtualFileSystem {
   // Uses deterministic UUID format for storage compatibility
   private static readonly VFS_ROOT_ID = '00000000-0000-0000-0000-000000000000'
 
+  // OPEN-PATH FIX: the dimension of the placeholder vector given to the VFS
+  // root when it is first created (see `doInitializeRoot`). Mirrors the
+  // built-in WASM embedding engine's fixed, hardcoded output size
+  // (all-MiniLM-L6-v2 — see src/embeddings/candle-wasm/src/lib.rs
+  // HIDDEN_SIZE and src/embeddings/EmbeddingManager.ts). Deliberately NOT
+  // derived from `brain.dimensions` — this constant only applies to the
+  // default-embedder branch, where the true output dimension is this fixed
+  // value by construction, never a moving target.
+  private static readonly VFS_ROOT_VECTOR_DIMENSIONS = 384
+
   /**
    * Construct a VFS bound to a Brainy instance.
    *
@@ -260,6 +270,40 @@ export class VirtualFileSystem implements IVirtualFileSystem {
     try {
       console.log('VFS: Creating root directory (fixed ID: 00000000-0000-0000-0000-000000000000)')
 
+      // OPEN-PATH FIX: the VFS root is Brainy's own system-tier plumbing — it
+      // is hidden from find()/getNounCount()/stats() by default and nothing
+      // ever runs a semantic search against it — so it needs no REAL
+      // embedding. Historically this add() always called embed('/'), which
+      // meant every writer's FIRST-EVER open forced the process-global WASM
+      // engine to cold-compile its model (measured 90-140s on throttled
+      // CPUs) before the brain could even finish init(). This branch only
+      // runs once per store (the root already exists — with a real vector —
+      // in every previously-opened production store; reopening never re-adds
+      // it), so the fix applies only to brand-new stores.
+      //
+      // Chosen fix: an explicit all-zero vector, not `deferEmbedding: true`.
+      // `deferEmbedding` looked attractive (ack now, embed later) but its
+      // landing path (`kickEmbedWorker()`, called synchronously right after
+      // commit — see brainy.ts add()/update()) would still force the WASM
+      // engine to cold-compile within milliseconds of open, just off the
+      // awaited path instead of never paying it at all — worse than the
+      // explicit-vector path, which never touches the engine for this row.
+      // An all-zero vector is safe: `cosineDistance` (src/utils/distance.ts)
+      // explicitly returns the MAXIMUM distance whenever either operand's
+      // norm is zero, so the root can never rank ahead of real content in a
+      // similarity search, and HNSW indexes it like any other vector.
+      //
+      // Only the default WASM engine gets this treatment — its output
+      // dimension (384) is fixed and hardcoded, so the placeholder can never
+      // mis-pin `brain.dimensions` for it. A plugin-registered native
+      // 'embeddings' provider has no cold-compile cost AND may use a
+      // different dimension, so it keeps embedding the root for real (same
+      // as before this fix) rather than risk pinning the wrong dimension
+      // ahead of the caller's own first real embed.
+      const rootVector = this.brain.usesDefaultWasmEmbedder()
+        ? new Array(VirtualFileSystem.VFS_ROOT_VECTOR_DIMENSIONS).fill(0)
+        : undefined
+
       await this.brain.add({
         id: rootId,  // Fixed ID - storage ensures uniqueness
         data: '/',
@@ -271,7 +315,8 @@ export class VirtualFileSystem implements IVirtualFileSystem {
         // public AddParams.visibility union ('public' | 'internal') — this is the single
         // sanctioned internal setter, hence the cast.
         visibility: 'system' as 'public' | 'internal',
-        metadata: this.getRootMetadata()
+        metadata: this.getRootMetadata(),
+        ...(rootVector ? { vector: rootVector } : {})
       })
 
       return rootId
@@ -1229,7 +1274,20 @@ export class VirtualFileSystem implements IVirtualFileSystem {
   }
 
   /**
-   * Read directory contents
+   * @description List a directory's contents. Non-recursive (default)
+   * returns direct children only, named by basename. `recursive: true`
+   * lists every descendant at any depth (files and directories), each
+   * reported as a path RELATIVE TO THE QUERIED DIRECTORY — matching Node's
+   * `fs.readdir(dir, { recursive: true })` convention — e.g. `'sub'` and
+   * `'sub/file.txt'` for a nested file. With `withFileTypes: true`, each
+   * {@link VFSDirent}'s `name` carries that same value (relative when
+   * recursive, basename otherwise); `path` is always the absolute VFS path
+   * either way.
+   * @param path - The directory to list.
+   * @param options - `recursive`, `withFileTypes`, `filter`, `sort`,
+   *   `offset`/`limit` (pagination applies AFTER filter/sort, over the full
+   *   recursive set when `recursive: true`).
+   * @throws {VFSError} ENOTDIR when `path` is not a directory.
    */
   async readdir(path: string, options?: ReaddirOptions): Promise<string[] | VFSDirent[]> {
     await this.ensureInitialized()
@@ -1242,8 +1300,12 @@ export class VirtualFileSystem implements IVirtualFileSystem {
       throw new VFSError(VFSErrorCode.ENOTDIR, `Not a directory: ${path}`, path, 'readdir')
     }
 
-    // Get children
-    let children = await this.pathResolver.getChildren(entityId)
+    // Direct children, or every descendant at any depth. gatherDescendants()
+    // is the same graph-traversal + ONE-batch-fetch path getTreeStructure()/
+    // getDescendants() already use — no per-directory storage round trips.
+    let children = options?.recursive
+      ? await this.gatherDescendants(entityId, Infinity)
+      : await this.pathResolver.getChildren(entityId)
 
     // Apply filters
     if (options?.filter) {
@@ -1267,17 +1329,29 @@ export class VirtualFileSystem implements IVirtualFileSystem {
     // Directory access time updates caused 50-100ms GCS write on EVERY readdir
     // await this.updateAccessTime(entityId)  // ← REMOVED
 
+    // The queried directory's own canonical (already-normalized) path — the
+    // base every recursive entry's relative name is computed against. Using
+    // the resolved entity's OWN path (rather than the raw `path` argument)
+    // means no separate normalization step is needed here.
+    const baseDir = entity.metadata.path
+    const relativeToBase = (childPath: string): string => {
+      const prefix = baseDir === '/' ? '/' : `${baseDir}/`
+      return childPath.startsWith(prefix) ? childPath.slice(prefix.length) : childPath
+    }
+
     // Return appropriate format
     if (options?.withFileTypes) {
       return children.map(child => ({
-        name: child.metadata.name,
+        name: options?.recursive ? relativeToBase(child.metadata.path) : child.metadata.name,
         path: child.metadata.path,
         type: child.metadata.vfsType,
         entityId: child.id
       } as VFSDirent))
     }
 
-    return children.map(child => child.metadata.name)
+    return children.map(child =>
+      options?.recursive ? relativeToBase(child.metadata.path) : child.metadata.name
+    )
   }
 
   // ============= Metadata Operations =============

src/vfs/types.ts

@@ -133,8 +133,17 @@ export interface VFSStats {
  * Directory entry (for readdir)
  */
 export interface VFSDirent {
+  /**
+   * The entry's basename (e.g. `'file.txt'`) when `readdir()` was called
+   * WITHOUT `recursive: true`. When `recursive: true` was set, this is
+   * instead the entry's path RELATIVE TO THE QUERIED DIRECTORY (e.g.
+   * `'sub/file.txt'` for a nested file) — the same value that would appear
+   * in the plain string-array form of a recursive `readdir()` call. `path`
+   * below always carries the absolute VFS path regardless of `recursive`,
+   * so nothing is lost either way.
+   */
   name: string
-  path: string                   // Full path
+  path: string                   // Full (absolute) VFS path — always absolute, recursive or not
   type: 'file' | 'directory' | 'symlink'
   entityId: string               // Underlying entity ID
 }
@@ -240,7 +249,15 @@ export interface ReaddirOptions {
   withFileTypes?: boolean        // Return Dirent objects
 
   // VFS-specific options
-  recursive?: boolean            // Include subdirectories
+  /**
+   * List every descendant (files and directories, all depths), not just
+   * direct children. Entries are reported as paths RELATIVE TO THE QUERIED
+   * DIRECTORY (Node's `fs.readdir(dir, { recursive: true })` convention) —
+   * a string-array result contains e.g. `'sub/file.txt'`, and with
+   * `withFileTypes: true` each `VFSDirent.name` carries that same relative
+   * path (see {@link VFSDirent}). Default: `false` (direct children only).
+   */
+  recursive?: boolean
   limit?: number                 // Max results
   offset?: number                // Skip N results
   cursor?: string                // Pagination cursor