fix(namespaces): deterministic catalog storageFor test (kill setTimeout flake) (#1564)

The "StorageRouter integration: catalog registers namespace on storageFor"
test relied on `await new Promise((r) => setTimeout(r, 10))` to let a
fire-and-forget `catalog.registerResolved(...)` — fired from the router's
`onResolve` hook inside `storageFor()` — settle before asserting the record
exists. Under CI contention 10ms was not always enough, so the assertion
intermittently failed (observed on an unrelated PR's quality job, passing on
rerun).

Add `NamespaceStorageRouter.whenResolveHooksSettled()`: the router now tracks
in-flight resolve-hook promises in a `pendingResolveHooks` set (added before
awaiting, removed when each settles — same lifecycle as `inFlightResolved`, so
it cannot grow unbounded). Callers can await it to observe the fire-and-forget
registrations `storageFor()` kicks off, deterministically, with no timer.

Replace the sleep in the target test and 4 sibling router-dedup tests with
`await router.whenResolveHooksSettled()`. Additive-only; no change to storage
resolution behavior.

Left unrelated setTimeout uses alone: the lock-release timing test and the
bounded `Promise.race` deadlock guards / interleaving seam settles.

Verified: 16 clean runs (10 sequential + 6 parallel under 8 saturated CPU
cores), 87/87 each; `tsc --noEmit`, preflight:quick, and entity-hardening
(245/245) all green. Independent of the #1546 category-dir work (PR #1563).

Author: joshuaswarren

packages/remnic-core/src/namespaces/catalog.test.ts

@@ -487,13 +487,13 @@ test("StorageRouter integration: catalog registers namespace on storageFor", asy
     const config = makeConfig(memoryDir);
     const catalog = new NamespaceCatalog(config);
     const router = new NamespaceStorageRouter(config, {
-      onResolve: (namespace, storageDir) => {
-        void catalog.registerResolved(namespace, storageDir);
-      },
+      // Return the registration promise so the router tracks it as in-flight and
+      // `whenResolveHooksSettled()` can await it deterministically (no timer race).
+      onResolve: (namespace, storageDir) => catalog.registerResolved(namespace, storageDir),
     });
     await router.storageFor("project-origin-abc123");
-    // allow the fire-and-forget registration to settle
-    await new Promise((r) => setTimeout(r, 10));
+    // Deterministically await the fire-and-forget registration instead of sleeping.
+    await router.whenResolveHooksSettled();
 
     const record = await catalog.getNamespaceRecord("project-origin-abc123");
     assert.ok(record, "storageFor should have registered the namespace");
@@ -2523,8 +2523,8 @@ test("an async onResolve hook rejection does not crash storage resolution", asyn
     // Must not throw or produce an unhandled rejection that fails the test.
     const sm = await router.storageFor("default");
     assert.ok(sm, "storage resolution succeeds despite a rejecting async hook");
-    // Give the swallowed rejection a tick to settle.
-    await new Promise((r) => setTimeout(r, 10));
+    // Deterministically await the swallowed rejection instead of sleeping.
+    await router.whenResolveHooksSettled();
     assert.ok(called >= 1, "the async hook was invoked");
   } finally {
     await rm(memoryDir, { recursive: true, force: true });
@@ -2564,7 +2564,7 @@ test("concurrent storageFor() for one namespace fires the resolve hook ONCE whil
     // Let the in-flight registration settle, then a steady-state cache hit must
     // still be a catalog no-op (now deduped via notifiedResolved).
     release();
-    await new Promise((r) => setTimeout(r, 10));
+    await router.whenResolveHooksSettled();
     await router.storageFor("project-origin-inflight");
     assert.equal(calls, 1, "a steady-state cache hit after settle must not re-fire the hook");
   } finally {
@@ -2589,20 +2589,20 @@ test("a dropped resolve registration (hook returns false) is retried on a later
     });
 
     await router.storageFor("project-origin-retry");
-    // Give the async hook a tick to settle and clear the in-flight marker.
-    await new Promise((r) => setTimeout(r, 10));
+    // Deterministically await the async hook so the in-flight marker is cleared.
+    await router.whenResolveHooksSettled();
     assert.equal(calls, 1, "the hook fired once for the dropped registration");
 
     // Now the registration will succeed; a later resolve must RETRY (not be
     // suppressed by a stale in-flight/notified marker from the dropped attempt).
     result = undefined; // success (legacy void)
     await router.storageFor("project-origin-retry");
-    await new Promise((r) => setTimeout(r, 10));
+    await router.whenResolveHooksSettled();
     assert.equal(calls, 2, "a dropped registration must be retried on the next storageFor()");
 
     // After a SUCCESSFUL registration, further cache hits are deduped (no retry).
     await router.storageFor("project-origin-retry");
-    await new Promise((r) => setTimeout(r, 10));
+    await router.whenResolveHooksSettled();
     assert.equal(calls, 2, "a successful registration is not re-fired on subsequent cache hits");
   } finally {
     await rm(memoryDir, { recursive: true, force: true });

packages/remnic-core/src/namespaces/storage.ts

@@ -223,6 +223,11 @@ export class NamespaceStorageRouter {
   // entry is always removed when the promise settles, so the map cannot grow
   // unbounded (one transient entry per concurrently-resolving namespace).
   private readonly inFlightResolved = new Map<string, string>();
+  // Tracks every in-flight resolve-hook promise so callers can deterministically
+  // await the fire-and-forget registrations that `storageFor()` kicks off (see
+  // `whenResolveHooksSettled`). Entries are removed as each hook settles, so the
+  // set holds at most one promise per concurrently-resolving namespace.
+  private readonly pendingResolveHooks = new Set<Promise<unknown>>();
 
   // Normalized (trimmed) default namespace identity (NH-FH). `storageFor`
   // normalizes its input, so default-namespace branches must compare against the
@@ -325,7 +330,10 @@ export class NamespaceStorageRouter {
       // the map holds at most one transient entry per concurrently-resolving
       // namespace and cannot grow unbounded.
       this.inFlightResolved.set(namespace, storageDir);
-      Promise.resolve(hook(namespace, storageDir)).then(
+      const hookResult = Promise.resolve(hook(namespace, storageDir));
+      // Track the in-flight promise so `whenResolveHooksSettled()` can await it.
+      this.pendingResolveHooks.add(hookResult);
+      hookResult.then(
         (persisted) => {
           // Clear the in-flight marker ONLY if it is still ours (a newer resolve
           // for a different dir may have replaced it).
@@ -338,6 +346,7 @@ export class NamespaceStorageRouter {
           // On `false` (dropped touch) we intentionally do NOT mark notified, so
           // a later `storageFor()` retries the registration. Clearing the
           // in-flight marker above is what re-enables that retry.
+          this.pendingResolveHooks.delete(hookResult);
         },
         () => {
           // Registration failed — clear in-flight AND do NOT mark as notified, so
@@ -348,6 +357,7 @@ export class NamespaceStorageRouter {
           if (this.notifiedResolved.get(namespace) === storageDir) {
             this.notifiedResolved.delete(namespace);
           }
+          this.pendingResolveHooks.delete(hookResult);
         },
       );
     } catch {
@@ -358,4 +368,21 @@ export class NamespaceStorageRouter {
       }
     }
   }
+
+  /**
+   * Resolve once every in-flight `onResolve` registration has settled.
+   *
+   * `storageFor()` fires the resolve hook fire-and-forget, so its catalog side
+   * effect (e.g. `registerResolved(...)`) is not observable the moment
+   * `storageFor()` returns. Callers that must act on that side effect — notably
+   * tests asserting the catalog was updated — should await this instead of
+   * racing a timer. Resolves immediately when no hook is registered or nothing
+   * is in flight. The loop re-checks because a settling hook could, in
+   * principle, trigger a follow-on resolution.
+   */
+  async whenResolveHooksSettled(): Promise<void> {
+    while (this.pendingResolveHooks.size > 0) {
+      await Promise.allSettled([...this.pendingResolveHooks]);
+    }
+  }
 }