@powerhousedao/switchboard 6.2.3-dev.44 → 6.2.3-dev.45

package/dist/server.d.mts

@@ -1,5 +1,5 @@
 import { ILogger } from "document-model";
-import { ChannelScheme, IDocumentModelLoader, IReactorClient, InProcessReactorClientModule, JwtHandler, ReactorBuilder, ReactorClientBuilder, ReactorFeatureFlags, SignerConfig, UnsupportedStoredDocuments, UnsupportedStoredProtocolError } from "@powerhousedao/reactor";
+import { ChannelScheme, IDocumentModelLoader, IReactorClient, InProcessReactorClientModule, JwtHandler, ModelManifestEntry, ReactorBuilder, ReactorClientBuilder, ReactorFeatureFlags, SignerConfig, UnsupportedStoredDocuments, UnsupportedStoredProtocolError } from "@powerhousedao/reactor";
 import { AttachmentReferenceProjectionCapability } from "@powerhousedao/reactor-api";
 import { IAttachmentService } from "@powerhousedao/reactor-attachments";
 import { IRenown } from "@renown/sdk/node";
@@ -206,6 +206,8 @@ export type SwitchboardReactor = {
   workflowTriggers?: WorkflowTriggersCapability;
   /** Whether workflows are on, after the option, PH_WORKFLOWS_ENABLED and the config file. */
   workflowsEnabled: boolean;
+  /** The boot list of importable models workers and workflow pieces load; empty when none are resolved. */
+  modelManifest(): ModelManifestEntry[];
   /** Present when the privacy add-on runs: its erasure service. */
   privacy?: {
     erasure: IErasureService;

package/dist/server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.mts","names":[],"sources":["../src/privacy.mts","../src/workflow-runtime.mts","../src/types.ts","../src/builder-defaults.mts","../src/unsupported-stored-documents.mts","../src/server.mts"],"mappings":";;;;;;;;;;;;KAyBY;;EAEV;;EAEA;;EAEA,SAAS;;;;;;KCsBC;EACN;;EAEA;EACA;;;;;;;;;;YCpCM;;YAKA,wBAAwB;EAClC,eAAe;;YAGL;EACV;EACA;EACA;;YAGU;;EAEV;;;;;EAKA;;EAGA;;YAGU;;;;;;;;;;;;;;;;;;;;;EAqBV,UAAU;;;;;;;;EAQV;;;;;;;EAOA;EACA;EACA;;;;;;EAMA;EACA;EACA;EACA,QAAQ;EACR;EACA;EACA;IAEM;IACA;;;;;;;EASN,WAAW;;EAEX;;;EAGA;;;EAGA;IACE;;;EAGF,UAAU;EACV,kBAAkB;EAClB;EACA;;;;;;EAMA;EACA,SAAS;;;;;;;;;;EAUT;;;;;;;;;;EAUA;;;;;;;;;EASA;IACE;IACA;IACA;;;;;;;;;;;EAWF;IACE;IACA;;;;;;;;;EASF,6BAA6B;;YAGnB;EACV;EACA,SAAS;;EAET,mBAAmB;;EAEnB,+BAA+B;;;EAG/B,mBAAmB;;EAEnB;;EAEA;IAAY,SAAS;;;EAErB;;EAEA,QAAQ;;;;;EAKR;;;;;;;;;;;;;EAaA,gBAAgB;;;;KC5MN;EAIV,iBAAiB;;EAEjB,mBAAmB;;EAEnB;;;;;;EAMA,gBAAgB;;EAEhB;;EAEA;IACE;IACA,eAAe,QAAQ;;;EAGzB,sBAAsB;EACtB,SAAS;;;;;;EAMT,SAAS;;;;;EAKT,cAAc,KAAK;;EAEnB,wBAAwB;;wBAsBV,gCACd,gBAAgB,gBAChB,eAAe,sBACf,UAAS;;;;wBC3EK,kCACd,OAAO,wCACP,KAAK,OAAO,aACX;;qBAaU,oCAAoC;WACtC;IAAqB;IAAkB;;WACvC;EAET,YAAY,OAAO;SAcZ,QAAQ,iBAAiB,SAAS;;;;;;;;;wBCyH3B,gBAAgB,eAAe;;wBAwI/B,8BACd,SAAS,KAAK,uDACd,oBACA,QAAQ;EACL;EAAmB,YAAY;;;;;;;;;;;;;;;;;;;qBAi+BvB,mBAAgB,UAClB,uBACR,QAAQ"}
+{"version":3,"file":"server.d.mts","names":[],"sources":["../src/privacy.mts","../src/workflow-runtime.mts","../src/types.ts","../src/builder-defaults.mts","../src/unsupported-stored-documents.mts","../src/server.mts"],"mappings":";;;;;;;;;;;;KAyBY;;EAEV;;EAEA;;EAEA,SAAS;;;;;;KC8BC;EACN;;EAEA;EACA;;;;;;;;;;YC3CM;;YAKA,wBAAwB;EAClC,eAAe;;YAGL;EACV;EACA;EACA;;YAGU;;EAEV;;;;;EAKA;;EAGA;;YAGU;;;;;;;;;;;;;;;;;;;;;EAqBV,UAAU;;;;;;;;EAQV;;;;;;;EAOA;EACA;EACA;;;;;;EAMA;EACA;EACA;EACA,QAAQ;EACR;EACA;EACA;IAEM;IACA;;;;;;;EASN,WAAW;;EAEX;;;EAGA;;;EAGA;IACE;;;EAGF,UAAU;EACV,kBAAkB;EAClB;EACA;;;;;;EAMA;EACA,SAAS;;;;;;;;;;EAUT;;;;;;;;;;EAUA;;;;;;;;;EASA;IACE;IACA;IACA;;;;;;;;;;;EAWF;IACE;IACA;;;;;;;;;EASF,6BAA6B;;YAGnB;EACV;EACA,SAAS;;EAET,mBAAmB;;EAEnB,+BAA+B;;;EAG/B,mBAAmB;;EAEnB;;EAEA,iBAAiB;;EAEjB;IAAY,SAAS;;;EAErB;;EAEA,QAAQ;;;;;EAKR;;;;;;;;;;;;;EAaA,gBAAgB;;;;KC/MN;EAIV,iBAAiB;;EAEjB,mBAAmB;;EAEnB;;;;;;EAMA,gBAAgB;;EAEhB;;EAEA;IACE;IACA,eAAe,QAAQ;;;EAGzB,sBAAsB;EACtB,SAAS;;;;;;EAMT,SAAS;;;;;EAKT,cAAc,KAAK;;EAEnB,wBAAwB;;wBAsBV,gCACd,gBAAgB,gBAChB,eAAe,sBACf,UAAS;;;;wBC3EK,kCACd,OAAO,wCACP,KAAK,OAAO,aACX;;qBAaU,oCAAoC;WACtC;IAAqB;IAAkB;;WACvC;EAET,YAAY,OAAO;SAcZ,QAAQ,iBAAiB,SAAS;;;;;;;;;wBCoK3B,gBAAgB,eAAe;;wBAoI/B,8BACd,SAAS,KAAK,uDACd,oBACA,QAAQ;EACL;EAAmB,YAAY;;;;;;;;;;;;;;;;;;;qBAm7BvB,mBAAgB,UAClB,uBACR,QAAQ"}

package/dist/server.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as resolveUnsupportedStoredDocuments, i as StoredDocumentsRefusedError, n as isPortAvailable, o as applySwitchboardReactorDefaults, r as startSwitchboard, t as deriveAttachmentServiceConfig } from "./server-Bk_IZzCn.mjs";
+import { a as resolveUnsupportedStoredDocuments, i as StoredDocumentsRefusedError, n as isPortAvailable, o as applySwitchboardReactorDefaults, r as startSwitchboard, t as deriveAttachmentServiceConfig } from "./server-Dvw8_NeM.mjs";
 export { StoredDocumentsRefusedError, applySwitchboardReactorDefaults, deriveAttachmentServiceConfig, isPortAvailable, resolveUnsupportedStoredDocuments, startSwitchboard };
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="72238471-a760-5883-8f43-7ff4b6802a34")}catch(e){}}();
-//# debugId=72238471-a760-5883-8f43-7ff4b6802a34
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b5bdc179-e9e6-50c3-a581-a82e554e7130")}catch(e){}}();
+//# debugId=b5bdc179-e9e6-50c3-a581-a82e554e7130

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@powerhousedao/switchboard",
   "type": "module",
-  "version": "6.2.3-dev.44",
+  "version": "6.2.3-dev.45",
   "main": "dist/index.mjs",
   "exports": {
     ".": {
@@ -41,7 +41,7 @@
     "@openfeature/core": "1.9.1",
     "@openfeature/env-var-provider": "0.3.1",
     "@openfeature/server-sdk": "1.19.0",
-    "@powerhousedao/config": "6.2.3-dev.44",
+    "@powerhousedao/config": "6.2.3-dev.45",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
@@ -55,23 +55,22 @@
     "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.41.1",
-    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.44",
-    "@powerhousedao/reactor": "6.2.3-dev.44",
-    "@powerhousedao/shared": "6.2.3-dev.44",
-    "@powerhousedao/vetra": "6.2.3-dev.44",
-    "@powerhousedao/reactor-api": "6.2.3-dev.44",
-    "@powerhousedao/reactor-attachments": "6.2.3-dev.44",
-    "@powerhousedao/reactor-drive": "6.2.3-dev.44",
-    "@powerhousedao/reactor-group": "6.2.3-dev.44",
-    "@powerhousedao/reactor-privacy": "6.2.3-dev.44",
-    "@powerhousedao/reactor-workflow": "6.2.3-dev.44",
-    "@powerhousedao/workflow": "6.2.3-dev.44",
-    "@powerhousedao/pglite-fs": "6.2.3-dev.44",
+    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.45",
+    "@powerhousedao/reactor": "6.2.3-dev.45",
+    "@powerhousedao/shared": "6.2.3-dev.45",
+    "@powerhousedao/vetra": "6.2.3-dev.45",
+    "@powerhousedao/reactor-api": "6.2.3-dev.45",
+    "@powerhousedao/reactor-attachments": "6.2.3-dev.45",
+    "@powerhousedao/reactor-drive": "6.2.3-dev.45",
+    "@powerhousedao/reactor-group": "6.2.3-dev.45",
+    "@powerhousedao/reactor-privacy": "6.2.3-dev.45",
+    "@powerhousedao/reactor-workflow": "6.2.3-dev.45",
+    "@powerhousedao/workflow": "6.2.3-dev.45",
     "@pyroscope/nodejs": "^0.4.5",
-    "@renown/sdk": "6.2.3-dev.44",
+    "@renown/sdk": "6.2.3-dev.45",
     "@sentry/node": "^10.53.1",
     "@sentry/opentelemetry": "^10.53.1",
-    "document-model": "6.2.3-dev.44",
+    "document-model": "6.2.3-dev.45",
     "dotenv": "^16.4.7",
     "express": "^4.22.1",
     "graphql": "^16",

package/test/boot-unsupported-stored-documents.test.ts

@@ -1,5 +1,5 @@
 import { PGlite } from "@electric-sql/pglite";
-import { AtomicNodeFs } from "@powerhousedao/pglite-fs";
+import { NodeFS } from "@electric-sql/pglite/nodefs";
 import {
   JobStatus,
   ReactorBuilder,
@@ -65,9 +65,7 @@ function stubLogger(): StubLogger {
 /** A reactor store holding one drive created at base-reducer 7. */
 async function seedStore(dir: string): Promise<void> {
   const db = new Kysely<Database>({
-    dialect: new ClosablePGliteDialect(
-      new PGlite({ fs: new AtomicNodeFs(dir) }),
-    ),
+    dialect: new ClosablePGliteDialect(new PGlite({ fs: new NodeFS(dir) })),
   });
   const module = await new ReactorBuilder()
     .withKysely(db)
@@ -89,7 +87,7 @@ async function seedStore(dir: string): Promise<void> {
       const { status } = await module.reactor.getJobStatus(created.id);
       return status === JobStatus.READ_READY || status === JobStatus.FAILED;
     },
-    // One job is ~40 full snapshots; the Windows runner needs the boot budget.
+    // PGlite is several times slower on the Windows runner.
     { timeout: BOOT_TIMEOUT, interval: 5 },
   );
   expect((await module.reactor.getJobStatus(created.id)).status).toBe(
@@ -97,6 +95,8 @@ async function seedStore(dir: string): Promise<void> {
   );
   await module.reactor.kill().completed;
   await db.destroy();
+  // PGlite leaves its lockfile behind after a clean close.
+  await rm(join(dir, "postmaster.pid"), { force: true });
 }
 
 // PGlite boots are several times slower on Windows runners.

package/test/durable-node-fs-pg16.test.ts

@@ -0,0 +1,80 @@
+import { createDurableNodeFs } from "@powerhousedao/reactor-api/pglite-node";
+import nodeFs, { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { loadNodeFsClass, loadPGliteModule } from "../src/pglite-version.js";
+
+// A fresh initdb takes ~10 s under suite load; the Windows runner is slower.
+const BOOT = 180_000;
+const COMMITS = 10;
+const RM = { recursive: true, force: true, maxRetries: 10 } as const;
+
+describe("durable NodeFS over pglite-legacy-02 (PG16)", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(async () => {
+    for (const dir of tempDirs.splice(0)) {
+      await fs.rm(dir, RM);
+    }
+  });
+
+  it(
+    "opens a PG16 dir over pglite-legacy-02 with the durable fs",
+    async () => {
+      const dir = await fs.mkdtemp(path.join(os.tmpdir(), "durable-pg16-"));
+      tempDirs.push(dir);
+      const counts = { fsync: 0, fdatasync: 0 };
+      const hostFs = {
+        fsyncSync: (fd: number) => {
+          counts.fsync++;
+          nodeFs.fsyncSync(fd);
+        },
+        fdatasyncSync: (fd: number) => {
+          counts.fdatasync++;
+          nodeFs.fdatasyncSync(fd);
+        },
+      };
+      const [{ PGlite }, NodeFS] = await Promise.all([
+        loadPGliteModule(16),
+        loadNodeFsClass(16),
+      ]);
+      const pg = new PGlite({
+        fs: createDurableNodeFs(NodeFS, dir, {
+          hostFs,
+          maintenanceIntervalMs: 0,
+        }),
+      });
+      try {
+        await pg.waitReady;
+        const version = await pg.query<{ v: string }>(
+          "SELECT current_setting('server_version_num') AS v",
+        );
+        expect(version.rows[0].v.startsWith("16")).toBe(true);
+        await pg.exec("CREATE TABLE t (v int)");
+        const before = counts.fdatasync;
+        for (let i = 0; i < COMMITS; i++) {
+          await pg.exec(`INSERT INTO t VALUES (${i})`);
+        }
+        const perCommit = counts.fdatasync - before;
+        const fsyncBefore = counts.fsync;
+        await pg.exec("CHECKPOINT");
+        const checkpointSyncs = counts.fsync - fsyncBefore;
+        console.info(
+          `pglite-legacy-02: ${perCommit} host fdatasync over ${COMMITS} commits, ${checkpointSyncs} host fsync on CHECKPOINT, ${fsyncBefore} host fsync since open`,
+        );
+        // Pins decision 5's outcome on 0.2.17: WAL goes through
+        // open_datasync, which never reaches the fdatasync hook, so commits
+        // are not synced; the stream-op patch does take (CHECKPOINT syncs).
+        expect(perCommit).toBe(0);
+        expect(checkpointSyncs).toBeGreaterThan(0);
+      } finally {
+        await pg.close();
+      }
+      expect(
+        (await fs.readFile(path.join(dir, "PG_VERSION"), "utf8")).trim(),
+      ).toBe("16");
+    },
+    BOOT,
+  );
+});

package/test/pglite-dialect.test.ts

@@ -26,6 +26,34 @@ describe("ClosablePGliteDialect", () => {
     expect(pglite.closed).toBe(true);
   });
 
+  it("tolerates a close that rejects because the runtime aborted", async () => {
+    const pglite = new PGlite();
+    created.push(pglite);
+    const db = new Kysely({ dialect: new ClosablePGliteDialect(pglite) });
+    await sql`select 1`.execute(db);
+    const realClose = pglite.close.bind(pglite);
+    pglite.close = () => {
+      pglite.close = realClose;
+      return Promise.reject(new Error("PGlite aborted: ENOSPC"));
+    };
+
+    await expect(db.destroy()).resolves.toBeUndefined();
+  });
+
+  it("rethrows a close that fails for any other reason", async () => {
+    const pglite = new PGlite();
+    created.push(pglite);
+    const db = new Kysely({ dialect: new ClosablePGliteDialect(pglite) });
+    await sql`select 1`.execute(db);
+    const realClose = pglite.close.bind(pglite);
+    pglite.close = () => {
+      pglite.close = realClose;
+      return Promise.reject(new Error("disk gone"));
+    };
+
+    await expect(db.destroy()).rejects.toThrow("disk gone");
+  });
+
   it("is idempotent if the PGlite is already closed", async () => {
     const pglite = new PGlite();
     created.push(pglite);

package/test/pglite-preflight.test.ts

@@ -0,0 +1,313 @@
+import { createDurableNodeFs } from "@powerhousedao/reactor-api/pglite-node";
+import type { ILogger } from "document-model";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { runPglitePreflight } from "../src/pglite-preflight.js";
+import { loadNodeFsClass, loadPGliteModule } from "../src/pglite-version.js";
+import { writeSnapshotFromDir } from "./snapshot-writer.js";
+
+// PGlite initdb and pg_dump are several times slower on the Windows runner.
+const BOOT_TIMEOUT = 120_000;
+const RM = { recursive: true, force: true, maxRetries: 10 } as const;
+const ROWS = 10;
+const CONVERTED_LINE =
+  /^Converted PGlite snapshot at (.+): snapshot (\d+) bytes -> (\d+) bytes on disk, (\d+) entries, (\d+) ms$/;
+
+type StubLogger = ILogger & {
+  debug: ReturnType<typeof vi.fn>;
+  info: ReturnType<typeof vi.fn>;
+  warn: ReturnType<typeof vi.fn>;
+};
+
+function stubLogger(): StubLogger {
+  const logger = {
+    verbose: vi.fn(),
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: vi.fn(),
+  };
+  logger.child.mockReturnValue(logger);
+  return logger as unknown as StubLogger;
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await fs.lstat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function pgVersion(dir: string): Promise<string> {
+  return (await fs.readFile(path.join(dir, "PG_VERSION"), "utf8")).trim();
+}
+
+/** Opens `dir` the way the server does and counts the seeded rows. */
+async function countRows(dir: string, major: 16 | 17): Promise<number> {
+  const [{ PGlite: Pg }, Base] = await Promise.all([
+    loadPGliteModule(major),
+    loadNodeFsClass(major),
+  ]);
+  const pg = new Pg({
+    fs: createDurableNodeFs(Base, dir, {
+      fsync: false,
+      maintenanceIntervalMs: 0,
+    }),
+  });
+  try {
+    await pg.waitReady;
+    const { rows } = await pg.query<{ n: number }>(
+      'SELECT count(*)::int AS n FROM "Rows"',
+    );
+    return rows[0].n;
+  } finally {
+    await pg.close();
+  }
+}
+
+function convertedLines(logger: StubLogger): string[] {
+  return logger.info.mock.calls
+    .map((call) => String(call[0]))
+    .filter((line) => CONVERTED_LINE.test(line));
+}
+
+describe("runPglitePreflight", () => {
+  // A pure-snapshot PG16 store: snapshot.bin and nothing else, the layout
+  // AtomicNodeFs left for a store it created itself.
+  let template: string;
+  let root: string;
+  let logger: StubLogger;
+
+  beforeAll(async () => {
+    template = await fs.mkdtemp(path.join(os.tmpdir(), "preflight-template-"));
+    const loose = path.join(template, "loose");
+    const { PGlite: LegacyPGlite } = await loadPGliteModule(16);
+    const LegacyNodeFS = await loadNodeFsClass(16);
+    const pg = new LegacyPGlite({ fs: new LegacyNodeFS(loose) });
+    await pg.waitReady;
+    await pg.exec('CREATE TABLE "Rows" (id int PRIMARY KEY, payload text)');
+    await pg.exec(
+      `INSERT INTO "Rows" SELECT g, repeat('x', 100) FROM generate_series(1, ${ROWS}) g`,
+    );
+    await pg.close();
+    await fs.rm(path.join(loose, "postmaster.pid"), { force: true });
+    expect(await pgVersion(loose)).toBe("16");
+
+    const store = path.join(template, "store");
+    await fs.mkdir(store);
+    await writeSnapshotFromDir(loose, path.join(store, "snapshot.bin"));
+    await fs.rm(loose, RM);
+  }, BOOT_TIMEOUT);
+
+  afterAll(async () => {
+    await fs.rm(template, RM);
+  }, BOOT_TIMEOUT);
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), "preflight-"));
+    logger = stubLogger();
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, RM);
+  }, BOOT_TIMEOUT);
+
+  async function snapshotDir(name: string): Promise<string> {
+    const dir = path.join(root, name);
+    await fs.cp(path.join(template, "store"), dir, { recursive: true });
+    return dir;
+  }
+
+  async function looseDir(name: string, major = 17): Promise<string> {
+    const dir = path.join(root, name);
+    await fs.mkdir(path.join(dir, "pg_wal"), { recursive: true });
+    await fs.writeFile(path.join(dir, "PG_VERSION"), `${major}\n`);
+    return dir;
+  }
+
+  it(
+    "converts before detecting the major, so a PG16 snapshot is migrated",
+    async () => {
+      const dir = await snapshotDir("reactor-storage");
+
+      const detected = await runPglitePreflight({
+        dirs: [dir],
+        migratePglite: true,
+        inMemory: false,
+        logger,
+      });
+
+      expect(detected.get(dir)).toBe(17);
+      expect(await pgVersion(dir)).toBe("17");
+      expect(await exists(path.join(dir, "snapshot.bin"))).toBe(false);
+      expect(await exists(`${dir}.converting`)).toBe(false);
+      expect(await exists(`${dir}.old`)).toBe(false);
+      expect(convertedLines(logger)).toHaveLength(1);
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining("Migrating"),
+      );
+      expect(await countRows(dir, 17)).toBe(ROWS);
+    },
+    BOOT_TIMEOUT,
+  );
+
+  // Pins the order alone: before this change a pure-snapshot dir had no loose
+  // PG_VERSION and the migration logged "No PG_VERSION; skipping". The case
+  // above also needs the legacy pg_dump to work.
+  it(
+    "attempts the migration of a PG16 snapshot instead of skipping it",
+    async () => {
+      const dir = await snapshotDir("reactor-storage");
+
+      await runPglitePreflight({
+        dirs: [dir],
+        migratePglite: true,
+        inMemory: false,
+        logger,
+      }).catch(() => undefined);
+
+      expect(convertedLines(logger)).toHaveLength(1);
+      expect(logger.info).not.toHaveBeenCalledWith(
+        expect.stringContaining("No PG_VERSION"),
+      );
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining(`Migrating ${dir} from PG16 to PG17`),
+      );
+    },
+    BOOT_TIMEOUT,
+  );
+
+  it(
+    "boots a converted dir on the second start without converting",
+    async () => {
+      const dir = await snapshotDir("reactor-storage");
+      const first = { dirs: [dir], inMemory: false, logger };
+      await runPglitePreflight(first);
+      expect(convertedLines(logger)).toHaveLength(1);
+      expect(await pgVersion(dir)).toBe("16");
+
+      const second = stubLogger();
+      const detected = await runPglitePreflight({ ...first, logger: second });
+
+      expect(detected.get(dir)).toBe(16);
+      expect(convertedLines(second)).toHaveLength(0);
+      expect(await exists(`${dir}.converting`)).toBe(false);
+      expect(await exists(`${dir}.old`)).toBe(false);
+      expect(await countRows(dir, 16)).toBe(ROWS);
+    },
+    BOOT_TIMEOUT,
+  );
+
+  it("removes pg_wal/xlogtemp.*", async () => {
+    const dir = await looseDir("read-storage");
+    const segment = path.join(dir, "pg_wal", "000000010000000000000001");
+    await fs.writeFile(segment, "wal");
+    await fs.writeFile(path.join(dir, "pg_wal", "xlogtemp.42"), "");
+    await fs.writeFile(path.join(dir, "pg_wal", "xlogtemp.7"), "");
+
+    const detected = await runPglitePreflight({
+      dirs: [dir],
+      inMemory: false,
+      logger,
+    });
+
+    expect(detected.get(dir)).toBe(17);
+    expect(await fs.readdir(path.join(dir, "pg_wal"))).toEqual([
+      "000000010000000000000001",
+    ]);
+    expect(await exists(segment)).toBe(true);
+  });
+
+  it("removes postmaster.pid without a warn call", async () => {
+    const dir = await looseDir("read-storage");
+    const lockfile = path.join(dir, "postmaster.pid");
+    await fs.writeFile(lockfile, "42\n");
+
+    await runPglitePreflight({ dirs: [dir], inMemory: false, logger });
+
+    expect(await exists(lockfile)).toBe(false);
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(logger.debug).toHaveBeenCalledWith(
+      expect.stringContaining(lockfile),
+    );
+  });
+
+  it(
+    "logs one info line per converted dir with sizes and duration",
+    async () => {
+      const reactor = await snapshotDir("reactor-storage");
+      const readModel = await snapshotDir("read-storage");
+
+      await runPglitePreflight({
+        dirs: [reactor, readModel],
+        inMemory: false,
+        logger,
+      });
+
+      const lines = convertedLines(logger);
+      expect(lines).toHaveLength(2);
+      const byDir = new Map(
+        lines.map((line) => {
+          const match = CONVERTED_LINE.exec(line)!;
+          return [match[1], match.slice(2).map(Number)] as const;
+        }),
+      );
+      for (const dir of [reactor, readModel]) {
+        const [snapshotBytes, convertedBytes, entries] = byDir.get(dir)!;
+        expect(snapshotBytes).toBeGreaterThan(0);
+        expect(convertedBytes).toBeGreaterThan(0);
+        expect(entries).toBeGreaterThan(0);
+      }
+    },
+    BOOT_TIMEOUT,
+  );
+
+  it("touches nothing in memory", async () => {
+    const dir = await snapshotDir("reactor-storage");
+
+    const detected = await runPglitePreflight({
+      dirs: [dir],
+      inMemory: true,
+      logger,
+    });
+
+    expect(detected.size).toBe(0);
+    expect(await exists(path.join(dir, "snapshot.bin"))).toBe(true);
+  });
+
+  it("wipes the dirs and their conversion siblings under forcePgVersion", async () => {
+    const dir = await snapshotDir("reactor-storage");
+    await fs.mkdir(`${dir}.old`);
+    await fs.mkdir(`${dir}.converting`);
+
+    const detected = await runPglitePreflight({
+      dirs: [dir],
+      forcePgVersion: 17,
+      migratePglite: true,
+      inMemory: false,
+      logger,
+    });
+
+    expect(detected.size).toBe(0);
+    expect(await exists(dir)).toBe(false);
+    expect(await exists(`${dir}.old`)).toBe(false);
+    expect(await exists(`${dir}.converting`)).toBe(false);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("ignoring --migrate-pglite"),
+    );
+  });
+});

package/test/pglite-version.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { parseForcePgVersion } from "../src/pglite-version.js";
+import { openForVerify, parseForcePgVersion } from "../src/pglite-version.js";
 
 describe("parseForcePgVersion", () => {
   it("returns null for undefined", () => {
@@ -35,3 +35,11 @@ describe("parseForcePgVersion", () => {
     expect(() => parseForcePgVersion("16.5")).toThrow(/PH_FORCE_PG_VERSION/);
   });
 });
+
+describe("openForVerify", () => {
+  it("throws on an unsupported major before touching disk", async () => {
+    await expect(openForVerify(15, "/nonexistent/pglite-dir")).rejects.toThrow(
+      /PG_VERSION=15 is not supported/,
+    );
+  });
+});

package/test/snapshot-writer.ts

@@ -0,0 +1,94 @@
+// Test-only v1 snapshot.bin writer over a loose on-disk tree.
+import { promises as fs } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import path from "node:path";
+
+const MAGIC = new Uint8Array([0x50, 0x47, 0x4c, 0x41]);
+const FORMAT_VERSION = 1;
+const HEADER_SIZE = 12;
+const ENTRY_PREFIX_SIZE = 9;
+const DEFAULT_SKIP = ["snapshot.bin", "snapshot.bin.tmp"];
+
+export interface SnapshotEntry {
+  type: 0 | 1;
+  mode: number;
+  relPath: string;
+  data?: Buffer;
+}
+
+export interface WriteSnapshotOptions {
+  /** Root-level names to leave out. Defaults to the snapshot files. */
+  skip?: string[];
+}
+
+export async function collectDiskEntries(
+  dataDir: string,
+  options: WriteSnapshotOptions = {},
+): Promise<SnapshotEntry[]> {
+  const skip = new Set(options.skip ?? DEFAULT_SKIP);
+  const entries: SnapshotEntry[] = [];
+  const walk = async (dir: string, rel: string) => {
+    const names = (await fs.readdir(dir)).sort();
+    for (const name of names) {
+      if (rel === "" && skip.has(name)) continue;
+      const full = path.join(dir, name);
+      const relPath = rel === "" ? name : `${rel}/${name}`;
+      const stat = await fs.lstat(full);
+      if (stat.isDirectory()) {
+        entries.push({ type: 0, mode: stat.mode & 0o7777, relPath });
+        await walk(full, relPath);
+      } else if (stat.isFile()) {
+        entries.push({
+          type: 1,
+          mode: stat.mode & 0o7777,
+          relPath,
+          data: await fs.readFile(full),
+        });
+      }
+    }
+  };
+  await walk(dataDir, "");
+  return entries;
+}
+
+export function encodeSnapshot(entries: SnapshotEntry[]): Buffer {
+  const encoder = new TextEncoder();
+  const parts: Buffer[] = [];
+  const header = Buffer.alloc(HEADER_SIZE);
+  header.set(MAGIC, 0);
+  header.writeUInt32LE(FORMAT_VERSION, 4);
+  header.writeUInt32LE(entries.length, 8);
+  parts.push(header);
+  for (const entry of entries) {
+    const pathBytes = encoder.encode(entry.relPath);
+    const dataLen = entry.data?.byteLength ?? 0;
+    const prefix = Buffer.alloc(ENTRY_PREFIX_SIZE + pathBytes.byteLength + 4);
+    prefix.writeUInt8(entry.type, 0);
+    prefix.writeUInt32LE(entry.mode, 1);
+    prefix.writeUInt32LE(pathBytes.byteLength, 5);
+    prefix.set(pathBytes, ENTRY_PREFIX_SIZE);
+    prefix.writeUInt32LE(dataLen, ENTRY_PREFIX_SIZE + pathBytes.byteLength);
+    parts.push(prefix);
+    if (entry.data && dataLen > 0) parts.push(entry.data);
+  }
+  return Buffer.concat(parts);
+}
+
+/** Serializes `dataDir` into `snapshotPath`. Returns the entry count and size. */
+export async function writeSnapshotFromDir(
+  dataDir: string,
+  snapshotPath: string,
+  options: WriteSnapshotOptions = {},
+): Promise<{ entries: number; bytes: number }> {
+  const entries = await collectDiskEntries(dataDir, options);
+  const bytes = encodeSnapshot(entries);
+  let fh: FileHandle | undefined;
+  try {
+    fh = await fs.open(snapshotPath, "w");
+    await fh.writeFile(bytes);
+    await fh.sync();
+  } finally {
+    await fh?.close();
+  }
+  return { entries: entries.length, bytes: bytes.byteLength };
+}