@di-framework/pglite-component 6.0.16 → 6.0.17

package/README.md

@@ -130,7 +130,7 @@ The pglite component is published to GitHub Container Registry (GHCR) as an OCI
 
 The workflow has four jobs:
 - `check-source` (`packages: read`) hashes the committed input files (`scripts/source-check.ts`). On a push it skips the build when `ghcr.io/di-framework/pglite-component:src-<hash>` already exists, so commits that do not change the component publish nothing.
-- `build` (no write token) runs the same targets as `ci.yml`: `make tools-rust`, `make unit smoke` (which runs `make build`, composing the provider with the engine via `wac plug`), then the publisher crates' clippy and tests.
+- `build` (no write token) runs the same targets as `ci.yml`: `make tools-rust`, `make unit smoke` (which runs `make build`, composing the provider with two instances of the engine via `wac compose`), then the publisher crates' clippy and tests.
 - `publish` (`packages: write`) downloads the tested `dist/` and runs `pglite-component-publisher`. It never rebuilds or modifies `dist/`. It checks `SHA256SUMS`, requires the export `di-framework:pglite/database@0.2.0` and rejects any import that is not `wasi:*`, then pushes the layer, config and manifest with `oras` under `ghcr.io/di-framework/pglite-component:<commit sha>` only, pulls it back with `wash` by the manifest digest to compare bytes, and only then points the version tag (`0.2.0`, the WIT package version) at that same manifest with `oras tag` and asserts both tags resolve to one digest. A failed check leaves the version tag where it was. The manifest and config carry a fixed `created` time (the publish step clears `SOURCE_DATE_EPOCH`, so `1970-01-01T00:00:00Z`), so publishing an unchanged `di-framework-pglite.wasm` gives the same digest and the pin job has nothing to pin. The `build` job passes the tested wasm sha256 to `publish`, which verifies it before pushing. It also tags the manifest `src-<hash>`.
 - `pin` (`contents: write`, `pull-requests: write`) opens or updates the PR `bot/pin-pglite-component`, "chore: pin pglite-component to <digest>", which rewrites the digests in this README with `scripts/pin-artifact.ts`. GitHub does not run workflows on a PR that `GITHUB_TOKEN` opened, so a maintainer has to start its checks (close and reopen it) before merging. It also runs when a push's source is already published (a revert to an older source, or a pin PR closed unmerged), so `main`'s pin follows the current source; it opens no PR when `main` already has the digest. On that path the `realign` job (`packages: write`) points the moving version tag back at that source's digest with `scripts/retag.sh`, which leaves a tag that is already there alone. Every tag move is behind the same source guard, so a stale run never retags.
 
@@ -139,7 +139,7 @@ Tags are movable. `0.2.0` always points to the latest `main` publish for WIT pac
 ### Artifact location
 
 The digest is in **Details** > **Record component digest** > **Step summary**, and in the `pglite-publish-report` artifact (`publish-report.json`).
-Published digest: `ghcr.io/di-framework/pglite-component@sha256:9be0cc2f59efea9ade293173ca28bd289a5505eb31b08fb954e718c03316355e`
+Published digest: `ghcr.io/di-framework/pglite-component@sha256:9d5b7c96aa4ad13c1c4de8d0285cf731b9926a47e0a7c680237708d26b439da3`
 
 **Note:** The GHCR package must be made public by an org admin after the first publish. Until then, only members with access to di-framework/platform can pull it.
 
@@ -177,7 +177,7 @@ wasmtime run --dir ./data::/data path/to/app.composed.wasm
 To use the published OCI component from GHCR instead (pin by digest for reproducibility):
 
 ```sh
-export PGLITE_REF='ghcr.io/di-framework/pglite-component@sha256:9be0cc2f59efea9ade293173ca28bd289a5505eb31b08fb954e718c03316355e'
+export PGLITE_REF='ghcr.io/di-framework/pglite-component@sha256:9d5b7c96aa4ad13c1c4de8d0285cf731b9926a47e0a7c680237708d26b439da3'
 wash oci pull "${PGLITE_REF}" pglite.wasm
 wac plug --plug pglite.wasm path/to/app.wasm -o path/to/app.composed.wasm
 mkdir -p ./data
@@ -196,8 +196,8 @@ savepoints, `rows-affected`, `close`, and `server-version`. PostgreSQL parameter
 use `$1`, `$2`, etc. Text parameters are sent with OID 0 (unknown type), allowing
 PostgreSQL to infer the type from context; comparisons against `uuid`, `timestamptz`,
 and `jsonb` columns work correctly (see Typed values). `server-version()` reports the bundled engine without
-opening a database. Only the `template1` database is currently supported;
-other `open-options.database` values are rejected. Requests must fit the engine's
+opening a database (see [Application database](#application-database) for
+`open-options.database`). Requests must fit the engine's
 input buffer; each serialized result is limited to 64 MiB and stays in memory.
 Larger results return a PostgreSQL program-limit error. Signal-based statement
 timeouts are unavailable in this WASI engine: nonzero `statement-timeout-ms`
@@ -211,6 +211,23 @@ and migrations run on embedded PostgreSQL. Compose your component with this
 provider (see above). The adapter is portable: it uses only
 `node:async_hooks`, which the framework's component toolchain shims.
 
+**Toolchain requirement for `int8` parameters past 2^53.** An exact `bigint`
+parameter beyond ±(2^53-1) needs componentize-qjs `0.4.4-di.5` or later, which
+`@di-framework/cli-plugin-platform` 6.2.0 or later installs. Use the default
+runtime, without `--sync` or `--opt-size`. When you install the compiler
+yourself, use the `di` dist-tag (`bun add @di-framework/componentize-qjs@di`):
+npm's `latest` tag of `@di-framework/componentize-qjs` still points at
+`0.4.4-di.1`. Older bindings, and the `--sync` / `--opt-size` runtimes, lower
+WIT `s64` only from Numbers, and such a parameter traps the guest instance
+instead of throwing a catchable error. Safe integers (`number` or `bigint`)
+are sent as Numbers and work on every binding.
+
+> **Upgrading.** Before this release, a `bigint` past 2^53 was sent as decimal
+> text. It is now sent as an exact `int8` integer. If your guest binds such
+> values, update the CLI plugin to 6.2.0 or later (componentize-qjs
+> `0.4.4-di.5`) before you update this package. Guests that bind only safe
+> integers need no change.
+
 ```ts
 import type { SqlDatabase } from '@di-framework/repo';
 import { createWasmPgliteDatabase } from '@di-framework/pglite-component';
@@ -233,8 +250,8 @@ handle and share it: every call goes through one async mutex.
 
 - **Transactions.** `transaction(fn)` runs the provider's `begin` and `commit`, and `rollback` when `fn` throws. Statements issued from inside `fn`, through the callback view or the outer handle, join the transaction; other tasks wait for it. Inside `fn`, prefer the callback view: while the transaction is open it joins from any async context, including a worker loop or `AsyncResource` created earlier, and Wasm-guest code that the `node:async_hooks` shim does not instrument (native async generators). The outer handle joins only from `fn`'s own async context. From any other context it waits for the mutex, so awaiting it from `fn` deadlocks. A nested `transaction()` opens a savepoint. When it throws, only its own work rolls back, and the outer transaction can continue. Its work commits only with the outer transaction. Sibling savepoints started concurrently run one at a time. A plain statement issued through a view while a sibling savepoint is open joins that savepoint and rolls back with it: in `Promise.all([tx.transaction(failing), (async () => { await work(); await tx.run(...); })()])`, a `run` issued while the savepoint is open lands inside it, so await the savepoint first when the statement must survive it. Statements issued concurrently inside one transaction reach the connection one at a time, also with bindings that return promises. `transaction()` on a view, called from another async context while a sibling savepoint is open, waits for that sibling to finish; if the sibling awaits that call, it waits forever. Joining lasts only while a transaction is open. A savepoint's callback view kept after the savepoint returns joins the nearest open ancestor while the root transaction is still open, and its work commits or rolls back with that ancestor. Once the root transaction has ended, a retained callback view, like a timer scheduled inside `fn`, waits for the mutex like any other caller and never runs inside another task's transaction.
 - **Placeholders.** `?` placeholders become `$1`, `$2`, ... in order (`toPgPlaceholders`). The rewrite skips `'...'` and `E'...'` strings, `"..."` identifiers, `$tag$...$tag$` bodies, `--` and `/* */` comments, and the jsonb operators `?|` and `?&`. Because of that, `?||` reads as `?|` followed by `|`: put a space in the concatenation (`? || 'x'`). The bare jsonb `?` operator looks like a placeholder: use `jsonb_exists(col, ?)` in a statement with parameters. A statement run without parameters is not rewritten. You can write `$n` yourself, but do not mix `$n` with `?` in one statement.
-- **Parameters.** `string` is sent as text, and PostgreSQL infers its type from context, so a UUID or timestamp string works against `uuid` and `timestamptz` columns. A safe integer is `int8`, another number is `float8`, a `boolean` is `bool`, and `Uint8Array`, `ArrayBuffer` and typed arrays are `bytea`. A `Date` is sent as an RFC 3339 timestamp. Plain objects and arrays are sent as JSON, so a JavaScript array is not a PostgreSQL array: pass a literal such as `'{a,b}'`. A `bigint` outside the safe integer range is sent as decimal text, so it is not rounded. A `number` that is an integer outside the safe range throws a `TypeError`, because it has already lost precision: pass a `bigint` or a decimal string for `int8`. NaN and Infinity are valid `float8` values and are sent as `real`.
-- **Results.** Values match the `wasmcloud:postgres` codec in `@di-framework/repo`, so repositories behave the same on both backends. `json` and `jsonb` are parsed. `timestamptz` is an ISO string with milliseconds (`2024-01-15T10:30:00.123Z`, microseconds truncated); `infinity` and BC dates are returned as PostgreSQL prints them. An `int8` outside the safe integer range is a decimal string, but only when the binding lifts WIT `s64` as a `bigint`; a binding that lifts it as a JavaScript number (componentize-qjs lowers `s64` from numbers) has already lost the precision, so cast large `int8` columns to `text` in the query (`id::text`) when exact values matter (#153). `bool` is a boolean, `bytea` is a `Uint8Array`, and `timestamp` without zone, `date`, `uuid`, `numeric` and arrays are strings.
+- **Parameters.** `string` is sent as text, and PostgreSQL infers its type from context, so a UUID or timestamp string works against `uuid` and `timestamptz` columns. A safe integer (`number` or `bigint`) is `int8`, sent as a JavaScript number, another number is `float8`, a `boolean` is `bool`, and `Uint8Array`, `ArrayBuffer` and typed arrays are `bytea`. A `Date` is sent as an RFC 3339 timestamp. Plain objects and arrays are sent as JSON, so a JavaScript array is not a PostgreSQL array: pass a literal such as `'{a,b}'`. A `bigint` past 2^53 that fits `int8` is sent as an exact `int8` with a `BigInt` payload, which needs componentize-qjs `0.4.4-di.5` or later (see the requirement above); one outside the `int8` range is sent as decimal text, so a `numeric` column receives it exactly. A `number` that is an integer outside the safe range throws a `TypeError`, because it has already lost precision: pass a `bigint` or a decimal string for `int8`. NaN and Infinity are valid `float8` values and are sent as `real`.
+- **Results.** Values match the `wasmcloud:postgres` codec in `@di-framework/repo`, so repositories behave the same on both backends. `json` and `jsonb` are parsed. `timestamptz` is an ISO string with milliseconds (`2024-01-15T10:30:00.123Z`, microseconds truncated); `infinity` and BC dates are returned as PostgreSQL prints them. An `int8` outside the safe integer range is an exact decimal string when the binding lifts WIT `s64` as a `bigint` (componentize-qjs `0.4.4-di.5` or later with the default runtime, or jco). Older componentize-qjs releases and the `--sync` / `--opt-size` runtimes lift `s64` as a Number, which has already rounded it, so cast large `int8` columns to `text` (`id::text`) on those. `bool` is a boolean, `bytea` is a `Uint8Array`, and `timestamp` without zone, `date`, `uuid`, `numeric` and arrays are strings.
 - **Errors.** Failures throw `WasmPgliteError` with the WIT `tag`. A PostgreSQL error keeps its SQLSTATE in `error.code` (`'23505'` for a unique violation), and the message starts with `PostgreSQL <code>`, so `isUniqueViolation` from `@di-framework/repo` works too.
 
 Pass `module` or `loadModule` to supply the interface yourself (for tests), and
@@ -360,11 +377,90 @@ libraries per engine instance. pgcrypto resolves before that table and never
 uses a slot. A `LOAD` of a new library after the table is full fails with
 `dlopen table is full` and leaves the session usable.
 
+### Application database
+
+Application data lives in the `postgres` database on data directories this
+provider initializes. Directories created before this release keep it in
+`template1` (#212). With `open-options.database` unset:
+
+| Data directory | Default database |
+| --- | --- |
+| Initialized by this provider: `<root>/data/di-framework-database` contains `postgres` | `postgres` |
+| No marker: created before this release (6.0.16 and earlier) | `template1`, unchanged |
+
+Upgrading the provider never moves data: an existing directory keeps opening
+`template1`, and it never gets the marker. Fresh directories open `postgres`
+from their first session on.
+
+**Do not roll back below this release for a directory it created.** Providers
+from before this release (6.0.16 and earlier) ignore the marker and open
+`template1`. On a directory created by this release, that database is empty:
+the application sees no data, may re-run its migrations, and writes into
+`template1`. Upgrading again brings the `postgres` data back, and everything
+written during the rollback stays stranded in `template1`. To roll back,
+either roll back to a build that reads the marker, or restore the backup of
+the root taken before the upgrade.
+
+Explicit `open-options.database` values:
+
+- `postgres` and `template1` are accepted. initdb creates both, so they exist
+  in every complete directory; on an older directory, `postgres` exists but is
+  empty. Before the engine starts, the provider checks that the database's
+  fixed-OID directory exists (`base/1` for `template1`, `base/5` for
+  `postgres`). If it does not, `open` fails with `open-failed`
+  (`database "postgres" has no data directory at base/5 ...`) and the same
+  component instance can still open `template1`. This is a filesystem check,
+  not a catalog lookup, so it does not catch every case:
+  - If initdb crashed while creating `postgres`, after copying `base/5` but
+    before committing the database, the check passes and an explicit
+    `postgres` open still stops the engine with
+    `FATAL: database "postgres" does not exist`. Only an initdb that crashed
+    partway through leaves a directory in this state, and with or without the
+    clean error such a directory is unfinished: re-create it (remove the root)
+    or restore it from a backup, do not use it.
+  - A `postgres` database that was dropped and re-created (new OID) or moved
+    with `ALTER DATABASE ... SET TABLESPACE` has no `base/5`, so the provider
+    refuses to open it although it exists.
+- `template0` is always rejected: the single-user engine would not enforce
+  `datallowconn`, so opening it would make the pristine template writable.
+- Any other name is rejected. The list is fixed because the engine picks its
+  database before its backend starts, so it cannot look the name up first.
+
+The embedded backend stays connected to the database its first `open` chose.
+A later `open` in the same component instance that resolves to a different
+database fails with `open-failed`; restart the component to switch.
+
+The marker is part of the data directory. Back it up and restore it with the
+rest of PGDATA. Without it, a directory falls back to `template1`, and an
+application whose tables are in `postgres` finds them missing; the provider
+cannot detect this. Do not add the marker by hand to a directory whose data
+is in `template1`. To move a legacy directory to `postgres`, export the data
+through the application and import it into a fresh directory, as described
+in [Upgrading across PostgreSQL major versions](#upgrading-across-postgresql-major-versions)
+(no `pg_dump` is bundled).
+
+Initialization runs in a separate, single-use engine instance bundled into
+the provider: initdb's post-bootstrap step runs in `template1` and the
+single-user backend cannot change databases afterwards. That instance creates
+the cluster and the marker. The serving instance then boots on the finished
+cluster in the selected database and verifies it with `current_database()`
+before the first session is handed out.
+
+Cost: the bootstrap instance runs only when a directory is created, but the
+component model cannot drop an instance, so its linear memory and its open
+files stay held until the process exits. The first start on a new directory
+peaks at about 690 MB RSS (about 106 MB more than a single engine) and holds
+about 43 more host file handles under the root. Later starts on an existing
+directory cost the same as before (about 264 MB in the smoke consumer).
+Restart the component after creating a directory if that memory matters.
+
 ## Persistence and ownership
 
 For an `open("/data/orders", ...)` call:
 
-- `/data/orders/data/` is PGDATA (catalogs, tables, WAL and configuration).
+- `/data/orders/data/` is PGDATA (catalogs, tables, WAL and configuration,
+  plus the `di-framework-database` marker on directories this provider
+  initialized; see [Application database](#application-database)).
 - `/data/orders/runtime/` contains bundled initialization/support files.
 - Bootstrap and shared-memory scratch files also stay beneath `/data/orders`.
 
@@ -440,7 +536,7 @@ for both the export and the import. PostgreSQL 18 is tracked in #401.
 - `js/wit.d.ts`: generated TypeScript view of the `database` interface.
 - `src/lib.rs`: public WIT resources and connection lifecycle.
 - `src/pgwire.rs`: PostgreSQL message encoding and typed rows, over memory.
-- `src/engine.rs`: persistent filesystem setup and exclusive engine access.
+- `src/engine.rs`: persistent filesystem setup, exclusive engine access, and the application database choice (marker, crash windows).
 - `engine/bridge.wat`: private canonical ABI bridge to the core engine.
 - `engine/build-pgcrypto.sh`: builds OpenSSL libcrypto and pgcrypto in the engine container and generates pgcrypto's static `dlsym` table; `scripts/patch-engine-source.ts` links both into the engine. The libcrypto build is cached under a key of the OpenSSL source tarball's sha256, the Configure options and `SOURCE_DATE_EPOCH`, so an OpenSSL version bump always rebuilds it.
 - `scripts/patch-engine-source.ts`: also replaces the upstream `dlopen` emulation's unbounded table (`dltab`) with the bounded one described under [Extensions](#extensions), and keeps pgcrypto's hook ahead of it.
@@ -448,5 +544,6 @@ for both the export and the import. PostgreSQL 18 is tracked in #401.
 - `scripts/build-engine.ts`: builds the engine source tree (pinned tag, checked commit, checked patches) and runs the wasipg container build; `scripts/check-engine-patch.ts` (`make check-engine-patch`) runs the same source steps without the build.
 - `scripts/prepare-engine.ts`: pinned engine preparation and componentization (all build scripts are Bun TypeScript; see `scripts/`).
 - `wit/deps/pglite-engine/engine.wit`: internal interface, composed away at build.
+- `wit/deps/pglite-engine-bootstrap/bootstrap.wit`: internal interface of the single-use initdb engine instance; `scripts/build.ts` (`providerWac`) feeds it from a second instance of the same engine component.
 
 Engine provenance and modifications are described in `engine/NOTICE`.

package/dist/BUILD-INFO.txt

@@ -1,6 +1,6 @@
 component:       di-framework:pglite@0.2.0
 profile:         release
-built:           2026-10-16T17:04:13Z
+built:           2026-10-17T04:21:44Z
 rustc:           rustc 1.97.1 (8bab26f4f 2026-07-14)
 target:          wasm32-wasip2
 wasm-tools:      wasm-tools 1.258.0 (5c6d31c78 2026-08-24)
@@ -13,4 +13,4 @@ engine-patch:    engine/patches/postgresql-17.11-wasi.patch (sha256 6beb64a561ca
 engine-recipe:   https://github.com/moznion/wasipg/tree/fa290be67946c0d3c4540bd1400b11e193d874e1
 adapter-sha256:  e51dd61669a20daca34befe7fdadf1ac84e4795a2c84a8400818ee1de5373ccc
 engine-sha256:   eb374344cff24c4cedacdad05a636a3b75b5eb1c4e55aa1a3ff9930be2ebc328
-size:            20168533 bytes
+size:            20176453 bytes

package/dist/SHA256SUMS

@@ -1,4 +1,4 @@
-a98a0476f61d539c72458be572d5705c8a237a49d51329784b65d564fab1b657  di-framework-pglite.wasm
-6053154ec1bc94de63ce4f4f4cce5922ef57dce794c2dde326f5845b8982d35f  di-framework-pglite.wit
-f76f82266b1f741e10c5c89e6c30f620571adba6bb228a33324681d2dc1822b3  BUILD-INFO.txt
+04cea641db9ac90a954fefd7783100175ce15bb2cc2e6fc47660fb4090eb2663  di-framework-pglite.wasm
+fcce3740d3bc8501368fa6c4686eb626a1e6d4d15d017817de273dfd77afcab9  di-framework-pglite.wit
+c3744f0613035d64fc6120bb9404a56e5759761e7cd64c55feeadd74b9727ad0  BUILD-INFO.txt
 443fd294671eb64972556656d3ee871e48448ad1169c012d18aa868568f628c1  THIRD-PARTY-NOTICES.txt

package/dist/di-framework-pglite.wit

@@ -1,6 +1,7 @@
 package root:component;
 
 world root {
+  import wasi:random/random@0.2.3;
   import wasi:io/poll@0.2.9;
   import wasi:clocks/monotonic-clock@0.2.9;
   import wasi:clocks/wall-clock@0.2.9;
@@ -18,11 +19,17 @@ world root {
   import wasi:cli/terminal-stderr@0.2.9;
   import wasi:filesystem/types@0.2.9;
   import wasi:filesystem/preopens@0.2.9;
-  import wasi:random/random@0.2.3;
 
   export di-framework:pglite/types@0.2.0;
   export di-framework:pglite/database@0.2.0;
 }
+package wasi:random@0.2.3 {
+  interface random {
+    get-random-bytes: func(len: u64) -> list<u8>;
+  }
+}
+
+
 package wasi:io@0.2.9 {
   interface poll {
     resource pollable {
@@ -40,16 +47,16 @@ package wasi:io@0.2.9 {
 
     resource input-stream {
       read: func(len: u64) -> result<list<u8>, stream-error>;
-      subscribe: func() -> pollable;
       blocking-read: func(len: u64) -> result<list<u8>, stream-error>;
+      subscribe: func() -> pollable;
     }
 
     resource output-stream {
       check-write: func() -> result<u64, stream-error>;
       write: func(contents: list<u8>) -> result<_, stream-error>;
+      blocking-write-and-flush: func(contents: list<u8>) -> result<_, stream-error>;
       blocking-flush: func() -> result<_, stream-error>;
       subscribe: func() -> pollable;
-      blocking-write-and-flush: func(contents: list<u8>) -> result<_, stream-error>;
     }
 
     variant stream-error {
@@ -64,15 +71,15 @@ package wasi:clocks@0.2.9 {
   interface monotonic-clock {
     use wasi:io/poll@0.2.9.{pollable};
 
-    type duration = u64;
-
     type instant = u64;
 
-    subscribe-duration: func(when: duration) -> pollable;
+    type duration = u64;
 
     now: func() -> instant;
 
     subscribe-instant: func(when: instant) -> pollable;
+
+    subscribe-duration: func(when: duration) -> pollable;
   }
   interface wall-clock {
     record datetime {
@@ -135,42 +142,47 @@ package wasi:cli@0.2.9 {
 
 package wasi:filesystem@0.2.9 {
   interface types {
-    use wasi:io/streams@0.2.9.{input-stream, output-stream};
-    use wasi:clocks/wall-clock@0.2.9.{datetime};
     use wasi:io/error@0.2.9.{error};
+    use wasi:clocks/wall-clock@0.2.9.{datetime};
+    use wasi:io/streams@0.2.9.{input-stream, output-stream};
 
     resource descriptor {
       read-via-stream: func(offset: filesize) -> result<input-stream, error-code>;
       write-via-stream: func(offset: filesize) -> result<output-stream, error-code>;
       append-via-stream: func() -> result<output-stream, error-code>;
+      advise: func(offset: filesize, length: filesize, advice: advice) -> result<_, error-code>;
+      sync-data: func() -> result<_, error-code>;
       get-flags: func() -> result<descriptor-flags, error-code>;
+      get-type: func() -> result<descriptor-type, error-code>;
+      set-size: func(size: filesize) -> result<_, error-code>;
+      read: func(length: filesize, offset: filesize) -> result<tuple<list<u8>, bool>, error-code>;
+      write: func(buffer: list<u8>, offset: filesize) -> result<filesize, error-code>;
       read-directory: func() -> result<directory-entry-stream, error-code>;
       sync: func() -> result<_, error-code>;
       create-directory-at: func(path: string) -> result<_, error-code>;
       stat: func() -> result<descriptor-stat, error-code>;
       stat-at: func(path-flags: path-flags, path: string) -> result<descriptor-stat, error-code>;
       open-at: func(path-flags: path-flags, path: string, open-flags: open-flags, %flags: descriptor-flags) -> result<descriptor, error-code>;
-      rename-at: func(old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>;
-      metadata-hash: func() -> result<metadata-hash-value, error-code>;
-      metadata-hash-at: func(path-flags: path-flags, path: string) -> result<metadata-hash-value, error-code>;
-      advise: func(offset: filesize, length: filesize, advice: advice) -> result<_, error-code>;
-      sync-data: func() -> result<_, error-code>;
-      get-type: func() -> result<descriptor-type, error-code>;
-      set-size: func(size: filesize) -> result<_, error-code>;
-      read: func(length: filesize, offset: filesize) -> result<tuple<list<u8>, bool>, error-code>;
-      write: func(buffer: list<u8>, offset: filesize) -> result<filesize, error-code>;
       readlink-at: func(path: string) -> result<string, error-code>;
       remove-directory-at: func(path: string) -> result<_, error-code>;
+      rename-at: func(old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>;
       symlink-at: func(old-path: string, new-path: string) -> result<_, error-code>;
       unlink-file-at: func(path: string) -> result<_, error-code>;
-    }
-
-    resource directory-entry-stream {
-      read-directory-entry: func() -> result<option<directory-entry>, error-code>;
+      metadata-hash: func() -> result<metadata-hash-value, error-code>;
+      metadata-hash-at: func(path-flags: path-flags, path: string) -> result<metadata-hash-value, error-code>;
     }
 
     type filesize = u64;
 
+    enum advice {
+      normal,
+      sequential,
+      random,
+      will-need,
+      dont-need,
+      no-reuse,
+    }
+
     enum error-code {
       access,
       would-block,
@@ -211,6 +223,10 @@ package wasi:filesystem@0.2.9 {
       cross-device,
     }
 
+    resource directory-entry-stream {
+      read-directory-entry: func() -> result<option<directory-entry>, error-code>;
+    }
+
     flags descriptor-flags {
       read,
       write,
@@ -231,6 +247,15 @@ package wasi:filesystem@0.2.9 {
       socket,
     }
 
+    record directory-entry {
+      %type: descriptor-type,
+      name: string,
+    }
+
+    flags path-flags {
+      symlink-follow,
+    }
+
     type link-count = u64;
 
     record descriptor-stat {
@@ -242,10 +267,6 @@ package wasi:filesystem@0.2.9 {
       status-change-timestamp: option<datetime>,
     }
 
-    flags path-flags {
-      symlink-follow,
-    }
-
     flags open-flags {
       create,
       directory,
@@ -258,20 +279,6 @@ package wasi:filesystem@0.2.9 {
       upper: u64,
     }
 
-    record directory-entry {
-      %type: descriptor-type,
-      name: string,
-    }
-
-    enum advice {
-      normal,
-      sequential,
-      random,
-      will-need,
-      dont-need,
-      no-reuse,
-    }
-
     filesystem-error-code: func(err: borrow<error>) -> option<error-code>;
   }
   interface preopens {
@@ -282,13 +289,6 @@ package wasi:filesystem@0.2.9 {
 }
 
 
-package wasi:random@0.2.3 {
-  interface random {
-    get-random-bytes: func(len: u64) -> list<u8>;
-  }
-}
-
-
 package di-framework:pglite@0.2.0 {
   interface types {
     record pg-error {

package/dist/js/adapter.d.ts

@@ -51,7 +51,13 @@ export interface WasmPgliteConnection {
 }
 /** The `open-options` record. Every field is optional. */
 export interface WasmPgliteOpenOptions {
-    /** Session database. The provider currently accepts only `template1`. */
+    /**
+     * Session database: `postgres` or `template1`. Unset selects the data
+     * directory's default: `postgres` for a directory the provider initialized
+     * (it writes a `di-framework-database` marker in PGDATA), `template1` for
+     * one created by an earlier release. The provider rejects `template0` and
+     * any other name.
+     */
     database?: string;
     /** Reserved by the provider: only `0` (or unset) is accepted. */
     statementTimeoutMs?: number;
@@ -87,9 +93,17 @@ export declare function unwrapWasmPgliteResult<T>(value: T | WasmResult<T>): T;
 /**
  * Converts a bound JavaScript parameter into a `value` variant.
  *
- * - `bigint` in the safe integer range becomes `integer`; a larger one is sent
- *   as `text` (OID 0), so PostgreSQL parses it for an `int8`/`numeric` column
- *   without rounding through a double.
+ * - Integers are sent in three bands:
+ *   - A safe integer (`number` or `bigint`, |v| <= 2^53-1) becomes `integer`
+ *     with a `number` payload. Every componentize-qjs release, including the
+ *     `--sync` / `--opt-size` runtimes, and jco lower WIT `s64` from it.
+ *   - A `bigint` past 2^53 that fits `int8` becomes `integer` with a `bigint`
+ *     payload, so it reaches PostgreSQL exact. That needs a binding that lowers
+ *     `s64` from `BigInt`: componentize-qjs 0.4.4-di.5 or later (default
+ *     runtime) or jco. Older componentize-qjs bindings trap on it.
+ *   - A `bigint` outside the `int8` range is sent as `text` (OID 0), so
+ *     PostgreSQL parses it for a `numeric` column instead of the binding
+ *     wrapping it modulo 2^64.
  * - A `number` that is an integer outside the safe range throws a `TypeError`
  *   (pass a `bigint` or string for `int8`); other non-safe numbers, including
  *   NaN and Infinity, are `real` (`float8`).

package/dist/js/adapter.js

@@ -84,12 +84,22 @@ export function unwrapWasmPgliteResult(value) {
 }
 const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
 const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_INT8 = 2n ** 63n - 1n;
+const MIN_INT8 = -(2n ** 63n);
 /**
  * Converts a bound JavaScript parameter into a `value` variant.
  *
- * - `bigint` in the safe integer range becomes `integer`; a larger one is sent
- *   as `text` (OID 0), so PostgreSQL parses it for an `int8`/`numeric` column
- *   without rounding through a double.
+ * - Integers are sent in three bands:
+ *   - A safe integer (`number` or `bigint`, |v| <= 2^53-1) becomes `integer`
+ *     with a `number` payload. Every componentize-qjs release, including the
+ *     `--sync` / `--opt-size` runtimes, and jco lower WIT `s64` from it.
+ *   - A `bigint` past 2^53 that fits `int8` becomes `integer` with a `bigint`
+ *     payload, so it reaches PostgreSQL exact. That needs a binding that lowers
+ *     `s64` from `BigInt`: componentize-qjs 0.4.4-di.5 or later (default
+ *     runtime) or jco. Older componentize-qjs bindings trap on it.
+ *   - A `bigint` outside the `int8` range is sent as `text` (OID 0), so
+ *     PostgreSQL parses it for a `numeric` column instead of the binding
+ *     wrapping it modulo 2^64.
  * - A `number` that is an integer outside the safe range throws a `TypeError`
  *   (pass a `bigint` or string for `int8`); other non-safe numbers, including
  *   NaN and Infinity, are `real` (`float8`).
@@ -101,14 +111,20 @@ export function toWasmPgValue(value) {
         return { tag: 'null' };
     switch (typeof value) {
         case 'bigint':
-            // componentize-qjs lowers WIT s64 from JS numbers (f64), not BigInt (#153).
+            // Safe values go as Numbers so bindings that lower s64 only from Numbers
+            // (componentize-qjs before 0.4.4-di.5, --sync, --opt-size) keep working.
             if (value >= MIN_SAFE && value <= MAX_SAFE) {
                 return { tag: 'integer', val: Number(value) };
             }
+            // Past 2^53 only a BigInt is exact (componentize-qjs 0.4.4-di.5+, jco).
+            if (value >= MIN_INT8 && value <= MAX_INT8) {
+                return { tag: 'integer', val: value };
+            }
             return { tag: 'text', val: value.toString() };
         case 'number':
             if (Number.isSafeInteger(value)) {
-                return { tag: 'integer', val: value };
+                // `+ 0` turns -0 into 0, which is the int8 PostgreSQL stores anyway.
+                return { tag: 'integer', val: value + 0 };
             }
             if (Number.isInteger(value)) {
                 // An integral double past 2^53 has already lost its low bits, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@di-framework/pglite-component",
-  "version": "6.0.16",
+  "version": "6.0.17",
   "type": "module",
   "description": "Embedded PostgreSQL component with persistent WASI storage and no TCP, plus its SqlDatabase adapter for @di-framework/repo.",
   "license": "(MIT OR Apache-2.0)",

package/wit/deps/pglite-engine-bootstrap/bootstrap.wit

@@ -0,0 +1,22 @@
+package di-framework:pglite-engine-bootstrap@0.1.0;
+
+/// Private: a second, single-use instance of the bundled engine that runs
+/// initdb on an empty data directory (#212).
+///
+/// The functions match `di-framework:pglite-engine/engine@0.1.0`; the build
+/// composes this import from a second instance of the same engine component
+/// (see `scripts/build.ts`). Like the engine import, it is never a host import
+/// in the final artifact.
+///
+/// Why a second instance: the engine's first backend session after initdb
+/// runs initdb's post-bootstrap SQL, which creates the `postgres` database
+/// from a `template1` session, and a single-user backend cannot change
+/// databases afterwards. The provider therefore initializes the cluster here
+/// and serves every session, the first included, from the main engine
+/// instance booted on the existing cluster with the selected database.
+interface bootstrap {
+  set-env: func(name: string, value: string) -> s32;
+  start: func(arguments: list<string>) -> s32;
+  initdb: func() -> s32;
+  backend: func();
+}

package/wit/world.wit

@@ -91,7 +91,15 @@ interface types {
   /// Options accepted by `open`. Every field is optional; `none` means the
   /// documented default.
   record open-options {
-    /// Database name for the session. Only `template1` is currently supported.
+    /// Database name for the session: `postgres` or `template1`.
+    ///
+    /// `none` selects the data directory's default. A directory this
+    /// provider initializes keeps application data in `postgres` and records
+    /// that with a `di-framework-database` marker in PGDATA. A directory
+    /// without the marker (one created by an earlier release) keeps using
+    /// `template1`, unchanged. `template0` and every other name fail `open`.
+    /// The engine stays in the database its first `open` selected until the
+    /// component restarts; a later `open` naming another one fails.
     database: option<string>,
     /// Reserved: WASI lacks the signal timer used for query cancellation.
     /// Only none or zero is supported; nonzero values fail open.
@@ -174,10 +182,11 @@ interface database {
 /// Kept symmetric with the sqlite-component: `types` is exported explicitly
 /// so the component is self-contained for `wac plug`.
 ///
-/// The private engine import is resolved during the provider build. The
+/// The private engine imports are resolved during the provider build. The
 /// shipped artifact has only WASI imports, including filesystem and randomness.
 world pglite-provider {
   import di-framework:pglite-engine/engine@0.1.0;
+  import di-framework:pglite-engine-bootstrap/bootstrap@0.1.0;
   export types;
   export database;
 }