0018: A World's PGlite cluster is prepared at image build

Status: Accepted. Date: 2026-10-07.

A World whose PostgreSQL is PGlite created its cluster on every fresh boot. A fresh up removes the instance directory, so PGlite 0.5.8 found no PG_VERSION in the empty data directory. It then ran initdb in a second wasm instance, dumped that cluster to a tar, unpacked the tar into the real data directory and synced every file to disk (PGlite#init, the initdb branch). After that, pglite-host.mjs opened template1 to create the declared database and role, closed it, and opened the declared database. In a browser tab every one of those file writes goes through the kernel. In Rallly's run 19, engine-doors' profile put the PGlite realm at 2.2 s, about 0.85 s of it in write-heavy file operations (writeFile, write, utimes, open and close on fresh files) on the data directory being created.

PGlite has its own path for an existing cluster: when PG_VERSION is present it logs "found DB, resuming" and starts Postgres on it. So the cluster is made once, where builds run, and the World's boot opens it.

• volter-world-infra prepare (with VOLTER_WORLD_CONFIG naming the World) runs the host itself with --prepare. That is the same openDeclaredDatabase path a serving host takes: initdb, the declared database and role, then a clean close(). The output is <World dir>/.volter-prepared/pglite-postgres-data, and a stamp beside it names the runtime's version (its host is the open path that made the cluster), its exact @electric-sql/pglite pin (initdb's encoding and locale are PGlite's defaults; the host passes no initdb parameters), and the declared user and database. The password is not in the cluster. The role is created without one, and the host's gateway checks the declared password on each connection, so a World with another password opens the same cluster correctly. The open path creates no extension in the cluster: they are loaded into the module at each open. Nothing is reimplemented. The bytes are the ones the same wasm writes on a first boot.
• At up, an empty PGlite data directory takes the prepared cluster by rename (a copy across file systems). It does so only when the stamp matches. Otherwise it boots as before and names the mismatch in the host's log. The host log also records the placement. A host started on a placed cluster is passed --prepared, and it opens the declared database directly: the template1 maintenance open, a whole second PGlite start, exists only to create that database and role, and the stamp vouches that they are there.
• The image build runs prepare on its host, after the World's packages are installed. The World's layer then carries .volter-prepared beside world.json, placed by reference as the World's packages are. That part belongs to browser-substrate's image builder.

A rename consumes the prepared cluster, so on a native machine only the first fresh boot after prepare takes it, and later fresh boots initialize as they always did. A tab re-applies the World's layer on each load. The seed is unchanged: stored data still arrives through the vendor's API after up.

EvidenceCopy Anchor Link

Unmeasured. The motivation is engine-doors' profile of Rallly run 19, relayed by the orchestrator. Neither the preparation nor the opened boot has been run (owner ruling 2026-10-07: code only). Thread B's Rallly run on this branch and on the image-builder branch gives the number.