onbuzz 5.6.1 → 5.6.2

package/config/default.json

@@ -0,0 +1,105 @@
+{
+  "system": {
+    "maxAgentsPerProject": 10,
+    "qualityInspectorInterval": 10,
+    "defaultModel": "anthropic-sonnet",
+    "stateDirectory": ".loxia-state",
+    "maxPauseDuration": 300
+  },
+
+  "auth": {
+    "sessionTtlHours": 168
+  },
+
+  "context": {
+    "maxSize": 50000,
+    "maxReferences": 10,
+    "autoValidation": true,
+    "cacheExpiry": 3600
+  },
+
+  "models": {
+    "routingTable": {
+      "coding": ["anthropic-sonnet", "gpt-4", "gpt-5.1-codex-mini", "deepseek-r1"],
+      "analysis": ["gpt-4", "phi-4", "phi-4-reasoning"],
+      "quick-tasks": ["anthropic-haiku", "gpt-4-mini", "phi-4"],
+      "creative": ["gpt-4", "gpt-5.1-codex-mini"],
+      "fallback": ["anthropic-sonnet"]
+    }
+  },
+
+  "tools": {
+    "terminal": {
+      "timeout": 30000,
+      "enabled": true
+    },
+    "filesystem": {
+      "maxFileSize": 10485760,
+      "enabled": true
+    },
+    "browser": {
+      "timeout": 60000,
+      "enabled": true
+    },
+    "agentdelay": {
+      "maxDuration": 300,
+      "minDuration": 1,
+      "enabled": true
+    }
+  },
+
+  "backend": {
+    "baseUrl": "https://loxia-api-g7hrb8bxdae8a2h7.z02.azurefd.net",
+    "timeout": 270000
+  },
+
+  "relay": {
+    "wsUrl": "wss://loxia-relay.redriver-dc902718.northeurope.azurecontainerapps.io/ws",
+    "pwaBaseUrl": "https://delightful-tree-06bb8f903.7.azurestaticapps.net"
+  },
+
+  "budget": {
+    "limit": 100.00,
+    "alertThreshold": 0.8,
+    "trackUsage": true
+  },
+
+  "logging": {
+    "level": "info",
+    "outputs": ["console"],
+    "colors": true,
+    "timestamp": true,
+    "logFile": "logs/loxia.log",
+    "maxFileSize": 10485760,
+    "maxFiles": 5
+  },
+
+  "interfaces": {
+    "cli": {
+      "enabled": true,
+      "historySize": 1000
+    },
+    "web": {
+      "enabled": true,
+      "port": 8080,
+      "host": "0.0.0.0"
+    },
+    "vscode": {
+      "enabled": true,
+      "contextMenus": true,
+      "statusBar": true
+    }
+  },
+
+  "visualEditor": {
+    "enabled": true,
+    "defaultViewMode": "embedded",
+    "serverUrl": "http://localhost:4000",
+    "serverPort": 4000,
+    "maxInstances": 3,
+    "idleTimeoutMs": 600000,
+    "retryAttempts": 3,
+    "retryDelayMs": 1000,
+    "connectionTimeoutMs": 10000
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "5.6.1",
+  "version": "5.6.2",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",
@@ -50,6 +50,7 @@
   "files": [
     "bin/",
     "src/",
+    "config/default.json",
     "web-ui/build/",
     "web-ui/dist/",
     "scripts/",
@@ -144,6 +145,7 @@
     },
     "files": [
       "src/**/*",
+      "config/default.json",
       "web-ui/build/**/*",
       "electron/**/*",
       "bin/**/*",

package/scripts/swap-brand.js

@@ -12,8 +12,8 @@
  * crash-looping). Any build that reads a swapped package.json must inherit
  * brand-correct artifact names.
  *
- * Usage: node scripts/swap-brand.js onbuzz
- * (Restore is a plain copy: package.autopilot.json → package.json.)
+ * Usage: node scripts/swap-brand.js onbuzz    — swap (refuses if already swapped)
+ *        node scripts/swap-brand.js restore  — copy the snapshot back + delete it
  */
 
 import fs from 'fs';
@@ -25,8 +25,33 @@ const pkgPath = path.join(ROOT, 'package.json');
 const backupPath = path.join(ROOT, 'package.autopilot.json');
 
 const target = process.argv[2];
-if (target !== 'onbuzz') {
-  console.error('Usage: node scripts/swap-brand.js onbuzz');
+if (target !== 'onbuzz' && target !== 'restore') {
+  console.error('Usage: node scripts/swap-brand.js onbuzz | restore');
+  process.exit(1);
+}
+
+if (target === 'restore') {
+  // Symmetric restore: byte-exact copy back, then DELETE the snapshot so a
+  // stale package.autopilot.json can never be restored over later edits or
+  // get committed. Idempotent: nothing to do when no snapshot exists.
+  if (!fs.existsSync(backupPath)) {
+    console.log('swap-brand: no package.autopilot.json snapshot — nothing to restore.');
+    process.exit(0);
+  }
+  fs.copyFileSync(backupPath, pkgPath);
+  fs.unlinkSync(backupPath);
+  console.log('swap-brand: restored Autopilot package.json (snapshot removed).');
+  process.exit(0);
+}
+
+const current = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+if (current.name === 'onbuzz') {
+  // REFUSE a double swap: snapshotting an already-swapped file would make
+  // "restore" restore the ONBUZZ identity — exactly how a swapped
+  // package.json survives to get committed (the v5.6.1 pre-release commit
+  // captured the onbuzz state). Run restore first.
+  console.error('swap-brand: package.json is ALREADY the onbuzz identity — refusing to snapshot it.');
+  console.error('Run `node scripts/swap-brand.js restore` first.');
   process.exit(1);
 }
 
@@ -35,7 +60,7 @@ if (target !== 'onbuzz') {
 // diffs after the restore).
 fs.copyFileSync(pkgPath, backupPath);
 
-const p = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+const p = current;
 
 // npm identity
 p.name = 'onbuzz';

package/src/core/__tests__/stateManager.atomicWrite.test.js

@@ -50,6 +50,47 @@ beforeEach(() => {
   mockUnlink.mockResolvedValue(undefined);
 });
 
+describe('saveJSON — serialization cost (mac event-loop stall incident)', () => {
+  test('small payloads stay pretty-printed (human-inspectable)', async () => {
+    const sm = makeSM();
+    await sm.saveJSON('/mock/userdata/state/small.json', { a: 1, nested: { b: 2 } });
+    const [, contents] = mockWriteFile.mock.calls[0];
+    expect(contents).toContain('\n  '); // indented
+  });
+
+  test('payloads over PRETTY_PRINT_LIMIT are written COMPACT (faster stringify, smaller file)', async () => {
+    const sm = makeSM();
+    const big = { blob: 'x'.repeat(StateManager.PRETTY_PRINT_LIMIT + 10) };
+    await sm.saveJSON('/mock/userdata/state/big.json', big);
+    const [, contents] = mockWriteFile.mock.calls[0];
+    expect(contents).not.toContain('\n');
+    expect(JSON.parse(contents)).toEqual(big); // same data, different formatting
+  });
+
+  test('slow serialization warns ONCE per file per minute with path/bytes/ms', async () => {
+    const sm = makeSM();
+    sm._slowSaveMs = 0; // every save counts as slow
+    await sm.saveJSON('/mock/userdata/state/slow.json', { a: 1 });
+    await sm.saveJSON('/mock/userdata/state/slow.json', { a: 2 }); // rate-limited
+    await sm.saveJSON('/mock/userdata/state/other.json', { a: 3 }); // separate file → own warn
+    const slow = sm.logger.warn.mock.calls.filter(([m]) => /SLOW state serialization/.test(m));
+    expect(slow).toHaveLength(2);
+    expect(slow[0][1]).toMatchObject({
+      filePath: '/mock/userdata/state/slow.json',
+      bytes: expect.any(Number),
+      stringifyMs: expect.any(Number),
+    });
+  });
+
+  test('fast saves never warn (threshold respected)', async () => {
+    const sm = makeSM();
+    sm._slowSaveMs = 60_000; // nothing is that slow
+    await sm.saveJSON('/mock/userdata/state/fast.json', { a: 1 });
+    const slow = sm.logger.warn.mock.calls.filter(([m]) => /SLOW state serialization/.test(m));
+    expect(slow).toHaveLength(0);
+  });
+});
+
 describe('saveJSON — atomic write', () => {
   test('writes to a temp file then renames it over the target', async () => {
     const sm = makeSM();

package/src/core/stateManager.js

@@ -69,6 +69,14 @@ export async function runWithConcurrency(taskFns, limit) {
 }
 
 class StateManager {
+  /**
+   * Above this many compact-JSON bytes, state files are written compact
+   * instead of pretty-printed. Pretty-printing is for human inspection;
+   * at multi-MB scale it only adds stringify time (a synchronous
+   * event-loop stall) and disk bytes.
+   */
+  static PRETTY_PRINT_LIMIT = 2 * 1024 * 1024;
+
   constructor(config, logger) {
     this.config = config;
     this.logger = logger;
@@ -91,6 +99,11 @@ class StateManager {
     // new write sitting on top of a longer old one — real corruption we've seen.
     this._writeChains = new Map();
     this._tmpWriteSeq = 0;
+    // Serialization stall attribution (mac incident: event-loop p99 in the
+    // SECONDS with 38–78MB conversation files). Saves slower than this warn,
+    // rate-limited per file, so production logs NAME the stalling file.
+    this._slowSaveMs = 250;
+    this._slowSaveWarnAt = new Map();
     
     // State file paths
     this.stateFiles = {
@@ -1241,7 +1254,28 @@ class StateManager {
     // restart) now only ever damages a throwaway temp file — the live file is
     // swapped in by an atomic rename or not at all; and two concurrent saves of
     // the same file can no longer interleave into a half-old/half-new mess.
-    const jsonData = JSON.stringify(data, null, 2);
+    // Stringify COMPACT first: pretty-printing is ~40% slower and ~35%
+    // bigger, and it happens SYNCHRONOUSLY on the event loop — on a 78MB
+    // conversation file that alone is seconds of stall (the mac
+    // "engine unresponsive" incident). Small files stay pretty-printed for
+    // human inspection; past the limit nobody reads them anyway.
+    const t0 = Date.now();
+    const compact = JSON.stringify(data);
+    const jsonData = compact.length <= StateManager.PRETTY_PRINT_LIMIT
+      ? JSON.stringify(data, null, 2)
+      : compact;
+    const stringifyMs = Date.now() - t0;
+    if (stringifyMs >= this._slowSaveMs) {
+      const now = Date.now();
+      const prev = this._slowSaveWarnAt.get(filePath) || 0;
+      if (now - prev >= 60_000) {
+        this._slowSaveWarnAt.set(filePath, now);
+        this.logger?.warn?.('[stateManager] SLOW state serialization — event-loop stall', {
+          filePath, bytes: jsonData.length, stringifyMs,
+          hint: 'this file is the stall culprit; consider splitting/compacting it',
+        });
+      }
+    }
     const key = path.resolve(filePath);
 
     const prior = this._writeChains.get(key) || Promise.resolve();

package/src/interfaces/webServer.js

@@ -7329,12 +7329,26 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
     let allConnections = [];
     if (sessionConnections.length === 0) {
       allConnections = Array.from(this.connections.values());
-      
-      this.logger?.warn('🔄 No connections for session, trying all connections:', {
-        targetSessionId: sessionId,
-        totalConnections: this.connections.size,
-        allSessionIds: Array.from(this.connections.values()).map(c => c.sessionId).filter(Boolean)
-      });
+
+      // Rate-limited: agents running with the UI closed (or its socket
+      // dropped) hit this on EVERY broadcast — a real mac log showed
+      // hundreds of these warns in minutes, drowning the signal. Warn at
+      // most once per session per minute; the count says what was elided.
+      const now = Date.now();
+      this._noConnWarnAt = this._noConnWarnAt || new Map();
+      const key = sessionId || '(none)';
+      const prev = this._noConnWarnAt.get(key);
+      if (!prev || now - prev.at >= 60_000) {
+        this.logger?.warn('🔄 No connections for session, trying all connections:', {
+          targetSessionId: sessionId,
+          totalConnections: this.connections.size,
+          allSessionIds: Array.from(this.connections.values()).map(c => c.sessionId).filter(Boolean),
+          elidedSinceLastWarn: prev?.elided ?? 0
+        });
+        this._noConnWarnAt.set(key, { at: now, elided: 0 });
+      } else {
+        prev.elided += 1;
+      }
     }
     
     const targetConnections = sessionConnections.length > 0 ? sessionConnections : allConnections;

package/src/services/embeddings/vectorStore/__tests__/inMemoryJsonStore.flushRace.test.js

@@ -0,0 +1,336 @@
+/**
+ * Flush serialization — regression for the mac ENOENT incident.
+ *
+ * Concurrent mutators used to race the SAME `<file>.tmp`: both wrote it,
+ * the first rename consumed it, the second rename failed
+ * `ENOENT: rename reminisce.vec.json.tmp -> reminisce.vec.json`
+ * (repeating on every reminisceIndexer tick in the mac production log).
+ * _flush() now chains every write behind the previous one; these tests pin
+ * the storm, the failure isolation, and caller-sees-own-error semantics.
+ */
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { InMemoryJsonStore } from '../inMemoryJsonStore.js';
+
+let dir;
+const FP = 'test-model@1';
+const vec = (seed) => Float32Array.from([seed, seed + 1, seed + 2]);
+
+async function makeStore(file = 'store.vec.json') {
+  const store = new InMemoryJsonStore({
+    filePath: path.join(dir, file), dimensions: 3, modelFingerprint: FP,
+  });
+  await store.load();
+  return store;
+}
+
+beforeEach(async () => {
+  dir = await fs.mkdtemp(path.join(os.tmpdir(), 'vecstore-race-'));
+});
+afterEach(async () => {
+  await fs.rm(dir, { recursive: true, force: true });
+});
+
+describe('concurrent flush storm (the production race)', () => {
+  test('50 parallel upserts: no ENOENT, every row lands, file is valid JSON', async () => {
+    const store = await makeStore();
+    await Promise.all(Array.from({ length: 50 }, (_, i) =>
+      store.upsert(`row-${i}`, vec(i), { i })));
+
+    const onDisk = JSON.parse(await fs.readFile(path.join(dir, 'store.vec.json'), 'utf8'));
+    expect(onDisk.rows).toHaveLength(50);
+
+    // A fresh instance reloads all 50 (proves the last write held full state)
+    const reread = await makeStore();
+    expect((await reread.stats()).count).toBe(50);
+  });
+
+  test('interleaved upsert/delete/deleteWhere storm settles consistent', async () => {
+    const store = await makeStore('mixed.vec.json');
+    await Promise.all([
+      ...Array.from({ length: 20 }, (_, i) => store.upsert(`keep-${i}`, vec(i), { kind: 'keep' })),
+      ...Array.from({ length: 20 }, (_, i) => store.upsert(`drop-${i}`, vec(i + 100), { kind: 'drop' })),
+    ]);
+    await Promise.all([
+      store.deleteWhere((m) => m.kind === 'drop'),
+      store.upsert('late', vec(7), { kind: 'keep' }),
+    ]);
+    const reread = await makeStore('mixed.vec.json');
+    const stats = await reread.stats();
+    expect(stats.count).toBe(21); // 20 keeps + late, 20 drops gone
+  });
+});
+
+describe('flush coalescing + stall attribution', () => {
+  test('a 50-mutation burst costs at most 2 snapshot writes (not 50)', async () => {
+    const store = await makeStore('coalesce.vec.json');
+    const real = store._writeSnapshot.bind(store);
+    const spy = jest.fn(real);
+    store._writeSnapshot = spy;
+    await Promise.all(Array.from({ length: 50 }, (_, i) =>
+      store.upsert(`burst-${i}`, vec(i), { i })));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+    const reread = await makeStore('coalesce.vec.json');
+    expect((await reread.stats()).count).toBe(50); // nothing lost to coalescing
+  });
+
+  test('mutation AFTER a write started queues a fresh link (no lost update)', async () => {
+    const store = await makeStore('fresh-link.vec.json');
+    let release;
+    const gate = new Promise((r) => { release = r; });
+    const real = store._writeSnapshot.bind(store);
+    let calls = 0;
+    store._writeSnapshot = async () => { calls += 1; if (calls === 1) await gate; return real(); };
+
+    const first = store.upsert('one', vec(1), {});
+    await Promise.resolve(); // let the first write START (clears _flushQueued)
+    const second = store.upsert('two', vec(2), {}); // must queue a NEW link
+    release();
+    await Promise.all([first, second]);
+    expect(calls).toBe(2);
+    const reread = await makeStore('fresh-link.vec.json');
+    expect((await reread.stats()).count).toBe(2);
+  });
+
+  test('slow snapshot warns with path/bytes/rows, rate-limited to 1/min', async () => {
+    const warns = [];
+    const store = new InMemoryJsonStore({
+      filePath: path.join(dir, 'slow.vec.json'), dimensions: 3, modelFingerprint: FP,
+      logger: { warn: (...a) => warns.push(a) },
+    });
+    await store.load();
+    store._slowWriteMs = 0; // every write counts as slow
+    await store.upsert('a', vec(1), {});
+    await store.upsert('b', vec(2), {}); // within the rate window → elided
+    const slow = warns.filter(([msg]) => /SLOW snapshot/.test(msg));
+    expect(slow).toHaveLength(1);
+    expect(slow[0][1]).toMatchObject({ rows: expect.any(Number), stringifyMs: expect.any(Number) });
+  });
+});
+
+describe('load / validation / drop edges (file to 100%)', () => {
+  test('constructor arg validation', () => {
+    expect(() => new InMemoryJsonStore({})).toThrow(/filePath/);
+    expect(() => new InMemoryJsonStore({ filePath: 'x', dimensions: 0 })).toThrow(/dimensions/);
+    expect(() => new InMemoryJsonStore({ filePath: 'x', dimensions: 1.5 })).toThrow(/dimensions/);
+    expect(() => new InMemoryJsonStore({ filePath: 'x', dimensions: 3 })).toThrow(/modelFingerprint/);
+  });
+
+  test('load edges: corrupt JSON, version/dims/fingerprint mismatch, junk rows, read error, idempotent', async () => {
+    const f = (name) => path.join(dir, name);
+    const mk = async (name, content) => { await fs.writeFile(f(name), content, 'utf8'); };
+    const open = async (name, dims = 3, fp = FP) => {
+      const st = new InMemoryJsonStore({ filePath: f(name), dimensions: dims, modelFingerprint: fp,
+        logger: { warn: () => {}, info: () => {} } });
+      await st.load();
+      await st.load(); // idempotent second call
+      return st;
+    };
+
+    await mk('corrupt.vec.json', '{nope');
+    expect((await (await open('corrupt.vec.json')).stats()).count).toBe(0);
+
+    await mk('vers.vec.json', JSON.stringify({ version: -1, dimensions: 3, modelFingerprint: FP, rows: [] }));
+    expect((await (await open('vers.vec.json')).stats()).count).toBe(0);
+
+    const good = { version: (JSON.parse(await fs.readFile(f('vers.vec.json'), 'utf8')).version, 1), dimensions: 3, modelFingerprint: FP };
+    // Determine the real FILE_VERSION by writing through the store itself:
+    const w = new InMemoryJsonStore({ filePath: f('probe.vec.json'), dimensions: 3, modelFingerprint: FP });
+    await w.load();
+    await w.upsert('p', vec(1), {});
+    const FILE_VERSION = JSON.parse(await fs.readFile(f('probe.vec.json'), 'utf8')).version;
+
+    await mk('dims.vec.json', JSON.stringify({ version: FILE_VERSION, dimensions: 99, modelFingerprint: FP, rows: [] }));
+    expect((await (await open('dims.vec.json')).stats()).count).toBe(0);
+
+    await mk('fp.vec.json', JSON.stringify({ version: FILE_VERSION, dimensions: 3, modelFingerprint: 'other@2', rows: [] }));
+    expect((await (await open('fp.vec.json')).stats()).count).toBe(0);
+
+    await mk('rows.vec.json', JSON.stringify({ version: FILE_VERSION, dimensions: 3, modelFingerprint: FP, rows: 'junk' }));
+    expect((await (await open('rows.vec.json')).stats()).count).toBe(0);
+
+    await mk('junkrows.vec.json', JSON.stringify({ version: FILE_VERSION, dimensions: 3, modelFingerprint: FP,
+      rows: [null, { id: 7 }, { id: 'short', vector: [1] }, { id: 'ok', vector: [1, 2, 3] }] }));
+    expect((await (await open('junkrows.vec.json')).stats()).count).toBe(1);
+
+    // read error that is NOT ENOENT (directory as file)
+    await fs.mkdir(f('dir.vec.json'));
+    expect((await (await open('dir.vec.json')).stats()).count).toBe(0);
+  });
+
+  test('mutator validation + assertLoaded + deleteWhere edges', async () => {
+    const store = await makeStore('valid.vec.json');
+    await expect(store.upsert('', vec(1), {})).rejects.toThrow(/non-empty string/);
+    await expect(store.upsert('a', [1, 2, 3], {})).rejects.toThrow(/Float32Array/);
+    await expect(store.upsert('a', Float32Array.from([1]), {})).rejects.toThrow(/dimensions/);
+    await expect(store.upsertBatch('nope')).rejects.toThrow(/array/);
+    await expect(store.upsertBatch([{ id: '', vector: vec(1) }])).rejects.toThrow(/needs an id/);
+    await expect(store.deleteWhere('nope')).rejects.toThrow(/predicate/);
+    await store.delete('missing'); // no-throw on unknown id
+    expect(await store.deleteWhere(() => false)).toBe(0); // zero removed → no flush
+
+    // update-in-place branch (existing id) + upsertBatch update branch
+    await store.upsert('u', vec(1), { v: 1 });
+    // throwing predicate = treated as no-match PER ROW (store must have rows)
+    expect(await store.deleteWhere(() => { throw new Error('boom'); })).toBe(0);
+    await store.upsert('u', vec(2), { v: 2 });
+    await store.upsertBatch([{ id: 'u', vector: vec(3), metadata: { v: 3 } }]);
+    await store.upsertBatch([{ id: 'u2', vector: vec(4) }]); // metadata defaulted
+    expect((await store.stats()).count).toBe(2);
+
+    // delete swap-remove middle element
+    await store.upsert('tail', vec(9), {});
+    await store.delete('u'); // not last → swap path
+    expect((await store.stats()).count).toBe(2);
+
+    const unloaded = new InMemoryJsonStore({ filePath: path.join(dir, 'x.vec.json'), dimensions: 3, modelFingerprint: FP });
+    await expect(unloaded.upsert('a', vec(1), {})).rejects.toThrow(/not loaded/);
+  });
+
+  test('deleteWhere swap-removes a MIDDLE row (index remap branch)', async () => {
+    const store = await makeStore('mid.vec.json');
+    await store.upsert('first', vec(1), { kill: true });
+    await store.upsert('second', vec(2), { kill: false });
+    await store.upsert('third', vec(3), { kill: false });
+    expect(await store.deleteWhere((m) => m.kill)).toBe(1); // 'first' is mid-array from the tail walk
+    const q = await store.query(vec(2), { topK: 5 });
+    expect(q.map((r) => r.id).sort()).toEqual(['second', 'third']);
+  });
+
+  test('drop(): removes file (missing file silent; unlink failure warns)', async () => {
+    const store = await makeStore('drop.vec.json');
+    await store.upsert('a', vec(1), {});
+    await store.drop();
+    await store.drop(); // second drop: file already gone → ENOENT swallowed
+    expect((await store.stats()).count).toBe(0);
+
+    const warns = [];
+    const werr = new InMemoryJsonStore({ filePath: path.join(dir, 'wd.vec.json'), dimensions: 3,
+      modelFingerprint: FP, logger: { warn: (...a) => warns.push(a) } });
+    await werr.load();
+    await fs.mkdir(path.join(dir, 'wd.vec.json')); // unlink on a dir → EPERM/EISDIR (not ENOENT)
+    await werr.drop();
+    expect(warns.length).toBe(1);
+  });
+
+  test('stats() lastIndexedAt picks the newest createdAt', async () => {
+    const store = await makeStore('ts.vec.json');
+    await store.upsert('a', vec(1), { createdAt: '2026-01-01T00:00:00Z' });
+    await store.upsert('b', vec(2), { createdAt: '2026-03-01T00:00:00Z' });
+    await store.upsert('c', vec(3), {}); // no timestamp branch
+    expect((await store.stats()).lastIndexedAt).toBe('2026-03-01T00:00:00Z');
+  });
+});
+
+describe('query / hybridQuery branches', () => {
+  async function seeded() {
+    const store = await makeStore('q.vec.json');
+    await store.upsertBatch([
+      { id: 'alpha', vector: vec(1), metadata: { text: 'alpha document', tag: 'a' } },
+      { id: 'beta',  vector: vec(5), metadata: { text: 'beta notes', tag: 'b' } },
+      { id: 'blank', vector: vec(9), metadata: { tag: 'a' } }, // no text branch
+    ]);
+    return store;
+  }
+
+  test('query: validation, filter, scoring adjuster, topK slice', async () => {
+    const store = await seeded();
+    await expect(store.query([1, 2, 3])).rejects.toThrow(/Float32Array/);
+
+    const all = await store.query(vec(1));
+    expect(all).toHaveLength(3);
+    expect(all[0].similarity).toBeDefined();
+
+    const filtered = await store.query(vec(1), { filter: (m) => m.tag === 'a' });
+    expect(filtered.map((r) => r.id).sort()).toEqual(['alpha', 'blank']);
+
+    const boosted = await store.query(vec(1), { scoring: (base, m) => (m.tag === 'b' ? base + 1000 : base) });
+    expect(boosted[0].id).toBe('beta');
+
+    expect(await store.query(vec(1), { topK: 1 })).toHaveLength(1);
+  });
+
+  test('hybridQuery: fuses substring + semantic; substring-only edges', async () => {
+    const store = await seeded();
+    const fused = await store.hybridQuery(vec(1), 'beta', { topK: 3 });
+    expect(fused.length).toBeGreaterThan(0);
+    expect(fused.some((r) => r.id === 'beta')).toBe(true);
+
+    // empty / non-string query text → substring list empty (still works)
+    expect((await store.hybridQuery(vec(1), '', { topK: 2 })).length).toBeGreaterThan(0);
+    expect((await store.hybridQuery(vec(1), null, { topK: 2 })).length).toBeGreaterThan(0);
+
+    // no match anywhere in substring path + filter applied
+    const filtered = await store.hybridQuery(vec(1), 'zzz-no-match', { filter: (m) => m.tag === 'a' });
+    expect(filtered.every((r) => r.metadata.tag === 'a')).toBe(true);
+
+    // defaults path (no opts object at all)
+    expect(Array.isArray(await store.hybridQuery(vec(1), 'alpha'))).toBe(true);
+
+    // TWO substring matches at different positions → the substring sort
+    // comparator actually runs (earlier match must rank higher)
+    await store.upsert('late-mention', vec(2), { text: 'notes about beta stuff' });
+    const two = await store.hybridQuery(vec(1), 'beta', { topK: 5 });
+    expect(two.filter((r) => ['beta', 'late-mention'].includes(r.id)).length).toBe(2);
+  });
+});
+
+describe('remaining default-arg + defensive branches', () => {
+  test('upsert/upsertBatch without metadata; delete the LAST row (no-swap branch)', async () => {
+    const store = await makeStore('defaults.vec.json');
+    await store.upsert('nometa', vec(1)); // metadata default {}
+    await store.upsertBatch([{ id: 'nometa', vector: vec(2) }]); // update-in-place, metadata || {} fallback
+    expect((await store.query(vec(1)))[0].metadata).toEqual({});
+    await store.upsert('tail', vec(3), {});
+    await store.delete('tail'); // idx === last → no swap
+    expect((await store.stats()).count).toBe(1);
+  });
+
+  test('hybridQuery tolerates a fused id that vanished from the index (defensive row-null branch)', async () => {
+    const store = await makeStore('phantom.vec.json');
+    await store.upsert('real', vec(1), { text: 'real thing' });
+    const realQuery = store.query.bind(store);
+    store.query = async (v, o) => {
+      const out = await realQuery(v, o);
+      return [{ id: 'phantom', score: 99, similarity: 0.99, metadata: {} }, ...out];
+    };
+    const fused = await store.hybridQuery(vec(1), 'real', { topK: 5 });
+    const phantom = fused.find((r) => r.id === 'phantom');
+    expect(phantom).toBeTruthy();
+    expect(phantom.metadata).toEqual({}); // row?.metadata || {} fallback
+  });
+});
+
+describe('failure isolation on the chain', () => {
+  test('a failing write rejects ITS caller only; later flushes succeed', async () => {
+    const store = await makeStore('fail.vec.json');
+    const real = store._writeSnapshot.bind(store);
+    let calls = 0;
+    store._writeSnapshot = jest.fn(async () => {
+      calls += 1;
+      if (calls === 1) throw new Error('disk hiccup');
+      return real();
+    });
+
+    await expect(store.upsert('a', vec(1), {})).rejects.toThrow('disk hiccup');
+    await expect(store.upsert('b', vec(2), {})).resolves.toBeUndefined();
+
+    const reread = await makeStore('fail.vec.json');
+    // Row 'a' mutated in memory before its flush failed; the SUCCESSFUL
+    // second flush persisted the newest state — both rows on disk.
+    expect((await reread.stats()).count).toBe(2);
+  });
+
+  test('explicit flush() rides the same chain', async () => {
+    const store = await makeStore('explicit.vec.json');
+    await Promise.all([
+      store.upsert('x', vec(1), {}),
+      store.flush(),
+      store.upsert('y', vec(2), {}),
+    ]);
+    const reread = await makeStore('explicit.vec.json');
+    expect((await reread.stats()).count).toBe(2);
+  });
+});