@volter/world-core 3.0.156 → 3.0.157

package/src/world-store.ts

@@ -52,6 +52,40 @@ import { randomUUID } from 'node:crypto';
 import { refuseReadOnlyWrite } from './request-scope.ts';
 import { basename, dirname, join, resolve } from 'node:path';
 
+// WHAT A LOCK HOLD ASKS (architecture, "What a hold asks is counted"): the file
+// store's questions counted inside an outermost lock hold and outside one, said at each outermost release where
+// VOLTER_TWIN_LOG=1 (storage.ts twinLog's gate and line), and not counted otherwise. Each counter counts the calls of
+// its own method: a readKept that misses its kept text, or meets a link, also counts the read it makes. A hold's
+// `heldMs` is the time of the hold's body, run once the lock is taken and before it is released, as the lock's release
+// line times its hold; the wait before the take is the wait line's `waitedMs`.
+const QUESTION_KINDS = ['generation', 'read', 'readKept', 'stat', 'exists', 'list', 'append'] as const;
+type QuestionCounts = Record<(typeof QUESTION_KINDS)[number], number>;
+// Read once, where a process is: a realm with none counts nothing.
+const questionsCounted = typeof process !== 'undefined' && process.env?.VOLTER_TWIN_LOG === '1';
+const noQuestions = (): QuestionCounts => ({ generation: 0, read: 0, readKept: 0, stat: 0, exists: 0, list: 0, append: 0 });
+let lockHoldDepth = 0;
+let questionsHeld = noQuestions();
+let questionsUnheld = noQuestions();
+function asked(kind: (typeof QUESTION_KINDS)[number]): void {
+  if (questionsCounted) (lockHoldDepth > 0 ? questionsHeld : questionsUnheld)[kind] += 1;
+}
+function countedHold<T>(operation: string, fn: () => T): () => T {
+  if (!questionsCounted) return fn;
+  return () => {
+    const began = Date.now();
+    lockHoldDepth += 1;
+    try { return fn(); }
+    finally {
+      lockHoldDepth -= 1;
+      if (lockHoldDepth === 0) {
+        const held = questionsHeld, before = questionsUnheld;
+        questionsHeld = noQuestions(); questionsUnheld = noQuestions();
+        try { console.error('[twin:store-lock]', JSON.stringify({ operation, heldMs: Date.now() - began, held, before })); } catch { /* an instrument */ }
+      }
+    }
+  };
+}
+
 /** Metadata a caller needs about a stored path. `isDirectory` distinguishes a JSON
  *  sidecar from a per-service subdir (validate/scrub walk on it); `size`+`mtimeMs`
  *  drive the append-dedupe index's cache-validity check in storage.ts. */
@@ -60,9 +94,31 @@ export type WorldStat = { size: number; mtimeMs: number; isDirectory: boolean; i
 /** Diagnostic context only; it does not change lock acquisition or stale-owner policy. */
 export type WorldLockOptions = { retainLiveOwner?: boolean; operation?: string; caller?: string };
 
-/** Capture at the outermost lock helper, then carry the same caller through nested helpers. */
+/**
+ * Capture at the outermost lock helper, then carry the same caller through nested helpers.
+ * LIMIT THE CAPTURE TO THE FRAMES READ (browser-substrate S2 R44, AC-LC3): V8's third frame supplies the caller,
+ * while new Error().stack normally collects up to Error.stackTraceLimit frames (ten by default).
+ * Retained browser-substrate LibreChat World-realm warm-up profiles 73/74 from runs 36c6d279 and 991f63e7e
+ * attributed about 10-57 ms self/inclusive to storageLockScope over each full 13.3-13.4 second profile window.
+ * Samples are about 5 ms apart. Those totals include this helper's capture, string and regex work; they are
+ * neither isolated capture time nor the credential doors' share. The co-located host serves doors on one loop.
+ * Original profiles are under /Users/aaronclaw/heavy-lead/librechat/logs-kept/:
+ * librechat-sn-36c6d279-e9e2632a-004051/cpuprofile/ (SHA256 prefixes 04dfc4fe, 77df6e8e) and
+ * librechat-sn-991f63e7e/cpuprofile/ (be6c6a93, 2fe80e7c), realms 73 and 74 respectively.
+ * The limit is lowered to three only for Error's own writable numeric data property above three, and restored
+ * only when lowered. Absent, accessor, non-writable and lower limits receive no writes. Existing constructor
+ * and user stack-formatter failure paths remain; this diagnostic optimization changes no lock ownership rule.
+ */
 export function storageLockScope(options: WorldLockOptions = {}): WorldLockOptions & { operation: string; caller: string } {
-  const frame = options.caller ? undefined : new Error().stack?.split('\n')[3];
+  let frame: string | undefined;
+  if (!options.caller) {
+    const held = Object.getOwnPropertyDescriptor(Error, 'stackTraceLimit');
+    const lowered = held !== undefined && 'value' in held && held.writable === true
+      && typeof held.value === 'number' && held.value > 3;
+    if (lowered) Error.stackTraceLimit = 3;
+    try { frame = new Error().stack?.split('\n')[3]; }
+    finally { if (lowered) Error.stackTraceLimit = held!.value as number; }
+  }
   const location = frame?.slice(frame.lastIndexOf('(') + 1).trim().replace(/^at\s+/, '');
   const site = location?.match(/^(.*):(\d+):\d+\)?$/);
   const caller = options.caller ?? (site ? `${site[1]!.replace(/^file:\/\//, '')}:${site[2]}` : 'unknown:0');
@@ -555,6 +611,7 @@ export class FsWorldStore implements WorldStore {
   // pays a kernel exchange for each, and a tree's stamp is a handful of these on every operation: Twenty's Redis twin
   // spent 54 s of 136 in `existsSync` and `statSync` under `treeStamp`, and its server's requests waited on it.
   read(path: string): string | null {
+    asked('read');
     try { return readFileSync(path, 'utf8'); }
     catch (error) { if (absent(error)) return null; throw error; }
   }
@@ -572,6 +629,7 @@ export class FsWorldStore implements WorldStore {
    */
   private readonly kept = new Map<string, { key: string; text: string }>();
   readKept(path: string): string | null {
+    asked('readKept');
     // A missing file is asked for without an error being made of it: a World with no parent has no branch.json, and
     // every stamp asks.
     let own: Stats | undefined;
@@ -613,6 +671,7 @@ export class FsWorldStore implements WorldStore {
    * World with a parent: its view and its ancestors' logs) is never kept under a generation (log.ts).
    */
   generation(dirPath: string): string | null {
+    asked('generation');
     let own: Stats | undefined;
     try { own = lstatSync(join(dirPath, TREE_GENERATION), { throwIfNoEntry: false }); }
     catch (error) { if (!absent(error)) throw error; }
@@ -661,6 +720,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   append(path: string, data: string): void {
+    asked('append');
     refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     this.kept.delete(path);
     // A tree's file in a tab: the generation's byte, the append and the byte again as one request of the kernel
@@ -712,6 +772,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   exists(path: string): boolean {
+    asked('exists');
     return existsSync(path);
   }
 
@@ -726,6 +787,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   list(dirPath: string): string[] {
+    asked('list');
     try { return readdirSync(dirPath); }
     catch (error) {
       // No such directory is an empty one, as before; a path that IS there and is not a directory still fails.
@@ -750,6 +812,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   stat(path: string): WorldStat | null {
+    asked('stat');
     // The path itself first: where it is no link, that is the whole answer. A link is followed by a second call,
     // and one that leads nowhere is absent, as it was.
     // Asked without an error being made of a missing path (a tree's parent log is absent in a World with no parent).
@@ -771,6 +834,7 @@ export class FsWorldStore implements WorldStore {
   withLock<T>(lockPath: string, fn: () => T, options: WorldLockOptions = {}): T {
     const started = Date.now();
     const scope = storageLockScope(options);
+    fn = countedHold(scope.operation, fn);
     let fd: number | null = null;
     // A kernel's file step takes the lock with its record in one request and keeps no descriptor (fileSteps).
     const steps = fileSteps();