fix(benchmark): persist remote fixture doc ids

Author: marcus-pousette

docs/BENCHMARKS.md

@@ -116,6 +116,8 @@ pnpm benchmark:sync:remote -- \
   --server-fixture-cache=reuse
 ```
 
+For remote targets, `prime` now records the exact fixture doc ID locally under `tmp/sqlite-node-sync-bench/server-fixtures/`. That means a fresh endpoint can be primed once with `--server-fixture-cache=rebuild`, and later `--server-fixture-cache=reuse` runs on the same machine can reopen that exact remote fixture doc instead of relying on historical deterministic fixture residue.
+
 By default, the local sync target runs the Postgres sync server in a spawned child process so local and remote measurements are closer to each other. When you add `--profile-backend`, the local target intentionally switches to the in-process server so per-backend timings are visible inside the benchmark process.
 
 Local server benchmarks now seed the Postgres backend directly before the timer starts. That keeps the measured path honest, because the actual sync to the client still goes through the real websocket server, while avoiding huge protocol-seed setup costs that are not part of the benchmark question.

packages/treecrdt-sqlite-node/scripts/bench-sync.ts

@@ -91,6 +91,7 @@ type PreparedServerFixture = {
   docId: string;
   cacheKey?: string;
   cacheStatus: 'disabled' | 'hit' | 'miss' | 'rebuild' | 'assumed';
+  cacheStatus: 'disabled' | 'hit' | 'miss' | 'rebuild' | 'assumed' | 'manifest';
   seedUploadMs?: number;
   seedAllReadyMs?: number;
   filterReadyMs?: number;
@@ -105,6 +106,7 @@ type SyncBenchConnection = {
 type SyncBenchTargetRuntime = {
   id: Exclude<SyncBenchTargetId, 'direct'>;
   serverProcess: 'child-process' | 'in-process' | 'remote';
+  fixtureCacheScope?: string;
   connect: (docId: string) => Promise<SyncBenchConnection>;
   seedOps?: (docId: string, ops: Operation[]) => Promise<void>;
   inspectDoc?: (docId: string) => Promise<{ allCount: number; maxLamport: number }>;
@@ -229,6 +231,14 @@ const SYNC_BENCH_POST_SEED_WAIT_MS = Math.max(0, envInt('SYNC_BENCH_POST_SEED_WA
 const DEFAULT_SERVER_FIXTURE_CACHE_MODE: ServerFixtureCacheMode = 'reuse';
 const SYNC_BENCH_SERVER_FIXTURE_CACHE_VERSION = '2026-03-21-v1';
 const SERVER_READY_POLL_MS = 100;
+const BENCH_REPO_ROOT = repoRootFromImportMeta(import.meta.url, 3);
+const SERVER_FIXTURE_MANIFEST_VERSION = 1;
+const SERVER_FIXTURE_MANIFEST_DIR = path.join(
+  BENCH_REPO_ROOT,
+  'tmp',
+  'sqlite-node-sync-bench',
+  'server-fixtures',
+);
 
 function envInt(name: string): number | undefined {
   const raw = process.env[name];
@@ -1163,6 +1173,7 @@ async function createLocalPostgresSyncServerTarget(
       id: 'local-postgres-sync-server',
       serverProcess: 'in-process',
       connect: async (docId) => await connectToSyncServer(`ws://127.0.0.1:${server.port}`, docId),
+      fixtureCacheScope: 'local-postgres-sync-server',
       seedOps,
       inspectDoc,
       resetDoc,
@@ -1221,6 +1232,7 @@ async function createLocalPostgresSyncServerTarget(
     id: 'local-postgres-sync-server',
     serverProcess: 'child-process',
     connect: async (docId) => await connectToSyncServer(`ws://127.0.0.1:${port}`, docId),
+    fixtureCacheScope: 'local-postgres-sync-server',
     seedOps,
     inspectDoc,
     resetDoc,
@@ -1329,6 +1341,7 @@ function createRemoteSyncServerTarget(baseUrl: string): SyncBenchTargetRuntime {
     id: 'remote-sync-server',
     serverProcess: 'remote',
     connect: async (docId) => await connectToSyncServer(baseUrl, docId, { client: 'builtin' }),
+    fixtureCacheScope: baseUrl,
     close: async () => {},
   };
 }
@@ -1656,6 +1669,71 @@ function createServerFixtureCacheKey(bench: ReturnType<typeof buildSyncBenchCase
   return hash.digest('hex').slice(0, 24);
 }
 
+function fixtureCacheScopeForRuntime(runtime: SyncBenchTargetRuntime): string {
+  return runtime.fixtureCacheScope ?? runtime.id;
+}
+
+function fixtureManifestPath(runtime: SyncBenchTargetRuntime, cacheKey: string): string {
+  const hash = createHash('sha256');
+  updateFixtureHashWithString(hash, fixtureCacheScopeForRuntime(runtime));
+  updateFixtureHashWithString(hash, cacheKey);
+  return path.join(
+    SERVER_FIXTURE_MANIFEST_DIR,
+    `${runtime.id}-${hash.digest('hex').slice(0, 24)}.json`,
+  );
+}
+
+async function readServerFixtureManifest(
+  runtime: SyncBenchTargetRuntime,
+  cacheKey: string,
+): Promise<string | undefined> {
+  try {
+    const raw = JSON.parse(await fs.readFile(fixtureManifestPath(runtime, cacheKey), 'utf8')) as {
+      version?: number;
+      runtimeId?: string;
+      scope?: string;
+      cacheKey?: string;
+      docId?: string;
+    };
+    if (
+      raw.version !== SERVER_FIXTURE_MANIFEST_VERSION ||
+      raw.runtimeId !== runtime.id ||
+      raw.scope !== fixtureCacheScopeForRuntime(runtime) ||
+      raw.cacheKey !== cacheKey ||
+      typeof raw.docId !== 'string' ||
+      raw.docId.length === 0
+    ) {
+      return undefined;
+    }
+    return raw.docId;
+  } catch {
+    return undefined;
+  }
+}
+
+async function writeServerFixtureManifest(
+  runtime: SyncBenchTargetRuntime,
+  cacheKey: string,
+  docId: string,
+): Promise<void> {
+  await fs.mkdir(SERVER_FIXTURE_MANIFEST_DIR, { recursive: true });
+  await fs.writeFile(
+    fixtureManifestPath(runtime, cacheKey),
+    JSON.stringify(
+      {
+        version: SERVER_FIXTURE_MANIFEST_VERSION,
+        runtimeId: runtime.id,
+        scope: fixtureCacheScopeForRuntime(runtime),
+        cacheKey,
+        docId,
+        writtenAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
 async function prepareServerFixture(
   runtime: SyncBenchTargetRuntime,
   bench: ReturnType<typeof buildSyncBenchCase>,
@@ -1666,12 +1744,18 @@ async function prepareServerFixture(
   const prepareStartedAt = performance.now();
   const cacheKey = cacheMode === 'off' ? undefined : createServerFixtureCacheKey(bench);
   const hasResettableFixture = runtime.resetDoc != null;
+  const manifestDocId =
+    cacheMode === 'reuse' && cacheKey != null && !runtime.inspectDoc
+      ? await readServerFixtureManifest(runtime, cacheKey)
+      : undefined;
   const docId =
     cacheMode === 'off'
       ? `sqlite-node-sync-bench-${runtime.id}-fixture-${crypto.randomUUID()}`
-      : cacheMode === 'rebuild' && !hasResettableFixture
-        ? `sqlite-node-sync-bench-${runtime.id}-fixture-${cacheKey}-${crypto.randomUUID()}`
-        : `sqlite-node-sync-bench-${runtime.id}-fixture-${cacheKey}`;
+      : cacheMode === 'reuse' && manifestDocId != null
+        ? manifestDocId
+        : cacheMode === 'rebuild' && !hasResettableFixture
+          ? `sqlite-node-sync-bench-${runtime.id}-fixture-${cacheKey}-${crypto.randomUUID()}`
+          : `sqlite-node-sync-bench-${runtime.id}-fixture-${cacheKey}`;
   if (cacheMode === 'reuse' && runtime.inspectDoc) {
     try {
       const current = await runtime.inspectDoc(docId);
@@ -1690,7 +1774,7 @@ async function prepareServerFixture(
     return {
       docId,
       cacheKey,
-      cacheStatus: 'assumed',
+      cacheStatus: manifestDocId != null ? 'manifest' : 'assumed',
     };
   }
   if (cacheMode !== 'off') {
@@ -1720,6 +1804,9 @@ async function prepareServerFixture(
     );
   }
   const filterReadyMs = performance.now() - filterReadyStartedAt;
+  if (cacheKey != null && !runtime.inspectDoc) {
+    await writeServerFixtureManifest(runtime, cacheKey, docId);
+  }
   return {
     docId,
     cacheKey,
@@ -2277,7 +2364,7 @@ async function primeServerFixtureCase(
 
 async function main() {
   const argv = process.argv.slice(2);
-  const repoRoot = repoRootFromImportMeta(import.meta.url, 3);
+  const repoRoot = BENCH_REPO_ROOT;
 
   const iterationsOverride = parseIterationsOverride(argv);
   const warmupIterationsOverride = parseWarmupIterationsOverride(argv);