@di-framework/sqlite-component 0.0.1 → 6.0.1

package/README.md

@@ -0,0 +1,250 @@
+# di-framework:sqlite — SQLite WebAssembly component
+
+A Rust WebAssembly component that bundles SQLite (amalgamation 3.53.2) and
+exposes it to other components through the `di-framework:sqlite@0.1.0` WIT
+package. Database files live on the WASI filesystem the host preopens for the
+component (a mounted volume), using rollback journals with `synchronous=FULL`.
+
+It exists so the QuickJS-based di-framework application component (built by
+`componentize-qjs` in `@di-framework/cli-plugin-platform`) can persist actor
+state, queue jobs and migration bookkeeping without a native SQLite in the JS
+runtime: the JS component *imports* `di-framework:sqlite/database`, this
+component *exports* it, and `wac plug` wires them into one component.
+
+```
+┌──────────────────────────────┐   di-framework:sqlite/database   ┌────────────────────────────┐
+│ app.wasm (componentize-qjs)  │ ───────── import ──────────────▶ │ di-framework-sqlite.wasm   │
+│  imports wasi:http, ...      │                                  │  exports database, types   │
+└──────────────────────────────┘                                  │  imports wasi:filesystem,  │
+                 └────────────── wac plug ────────────────────────┤          wasi:clocks, cli  │
+                                    │                             └────────────────────────────┘
+                                    ▼
+                          composed.wasm  (only wasi:* / wasmcloud:* imports remain)
+```
+
+## Layout
+
+```
+packages/di-framework-sqlite-component/
+├── Cargo.toml, Cargo.lock        pinned crates (rusqlite 0.40.2, libsqlite3-sys 0.38.2, wit-bindgen 0.61.1, cc 1.4.5)
+├── rust-toolchain.toml           Rust 1.97.1 + wasm32-wasip2 (honoured by rustup)
+├── .cargo/config.toml            default target + C toolchain env + SQLite compile flags
+├── build.rs                      compiles csrc/wasi-vfs.c with the same wasi-sdk clang
+├── csrc/wasi-vfs.c               SQLite VFS over wasi-libc (see "Persistence model")
+├── wit/world.wit                 di-framework:sqlite@0.1.0
+├── src/lib.rs                    the component (exports database + types)
+├── scripts/
+│   ├── tool-versions.env         every pinned version + SHA-256
+│   ├── install-tools.sh          checksum-verified installer for wasm-tools, wac, wasi-sdk (+ optional rustup)
+│   ├── env.sh                    puts .tools/ on PATH and exports build env (sourceable)
+│   ├── build.sh                  cargo build + validate + stage dist/
+│   ├── compose.sh                wac plug <consumer> with the provider
+│   └── smoke.sh                  end-to-end test under wasmtime
+├── tests/smoke-consumer/         wasip2 command component importing the interface (used by smoke.sh)
+├── Makefile                      thin wrapper around the scripts
+└── dist/  (generated)            di-framework-sqlite.wasm, .wit, BUILD-INFO.txt, SHA256SUMS
+```
+
+## Building
+
+```sh
+cd packages/di-framework-sqlite-component
+
+make tools        # wasm-tools 1.258.0, wac 0.11.0, wasi-sdk 34.0 -> .tools/ (SHA-256 verified)
+make tools-rust   # only if you have no rustup: hermetic rustup + Rust 1.97.1 + wasm32-wasip2 -> .tools/
+make build        # -> dist/di-framework-sqlite.wasm (~1.2 MB)
+make smoke        # compose with tests/smoke-consumer and run under wasmtime (needs `wasmtime` on PATH)
+```
+
+`make build` runs `scripts/build.sh`, which is:
+
+```sh
+. scripts/env.sh                                     # PATH, CC_wasm32_wasip2, LIBSQLITE3_FLAGS, RUSTFLAGS
+cargo build --locked --release --target wasm32-wasip2 -p di-framework-sqlite-component
+wasm-tools validate --features all dist/di-framework-sqlite.wasm
+wasm-tools component wit dist/di-framework-sqlite.wasm > dist/di-framework-sqlite.wit
+```
+
+Requirements: a C compiler that targets `wasm32-wasip2` with wasi-libc headers
+(the pinned wasi-sdk; Apple clang has no wasm backend), Rust 1.97.1 with the
+`wasm32-wasip2` std, `wasm-tools`. `rustc` on `wasm32-wasip2` emits a component
+directly (via `wasm-component-ld`), so no `wasm-tools component new` step is
+needed. Builds are deterministic: `--remap-path-prefix` strips absolute paths
+and `dist/SHA256SUMS` is identical across clean rebuilds on the same toolchain.
+
+### Pinning and checksums
+
+`scripts/tool-versions.env` is the single source of truth. `install-tools.sh`
+downloads release assets from GitHub / static.rust-lang.org, compares the
+SHA-256 against the pinned value **before** unpacking or executing anything,
+and aborts on mismatch. Hashes are recorded for macOS (arm64, x86_64) and Linux
+(x86_64, aarch64). To upgrade: bump the version, download the new assets,
+`shasum -a 256`, update the file, rebuild, run `make smoke`.
+
+Rust itself is pinned by `rust-toolchain.toml` (rustup verifies components
+against the signed channel manifest). Crates are pinned with `=` in
+`Cargo.toml` and locked in `Cargo.lock`; `--locked` refuses to drift.
+
+### Environment overrides
+
+| Variable | Meaning |
+| --- | --- |
+| `DF_SQLITE_TOOLS_DIR` | where `install-tools.sh` installs (default `.tools/`) |
+| `WASI_SDK_PATH` | use an existing wasi-sdk instead of downloading |
+| `CC_wasm32_wasip2`, `AR_wasm32_wasip2`, `CFLAGS_wasm32_wasip2` | C toolchain for `sqlite3.c` + `wasi-vfs.c` |
+| `LIBSQLITE3_FLAGS` | extra `-D` flags for the amalgamation (see `.cargo/config.toml`) |
+
+## WIT interface (`di-framework:sqlite@0.1.0`)
+
+Full text in [`wit/world.wit`](wit/world.wit). Summary:
+
+**`types`**
+- `value`: `null | integer(s64) | real(f64) | text(string) | blob(list<u8>)`
+- `row = list<tuple<string, value>>` — column name / value pairs, in column order
+- `error`: `open-failed(string) | closed | invalid-sql(string) | invalid-params(string) | execution-failed(sqlite-error) | value-conversion-failed(string) | busy | invalid-transaction-state(string) | other(string)`
+- `sqlite-error { code, extended-code, message }` — e.g. `19`/`1555` for a primary-key violation
+- `open-options { create?, read-only?, synchronous?, journal-mode?, busy-timeout-ms?, foreign-keys? }`
+- enums `sync-mode { off, normal, full }`, `journal-mode { delete, persist, memory }`, `transaction-behavior { deferred, immediate, exclusive }`
+
+**`database`**
+- `open(path, option<open-options>) -> result<connection, error>`
+- `sqlite-version() -> string`
+- `resource connection`
+  - `exec(sql)` — multi-statement batch, no params, no results (DDL / migrations / pragmas)
+  - `run(sql, params) -> u64` — one statement, returns `changes`
+  - `query(sql, params) -> list<row>`
+  - `first(sql, params) -> option<row>`
+  - `begin(option<transaction-behavior>)` (default `immediate`), `commit()`, `rollback()`
+  - `savepoint(name)`, `release-savepoint(name)`, `rollback-to-savepoint(name)` — nesting
+  - `in-transaction() -> bool`, `changes() -> u64`, `last-insert-rowid() -> s64`
+  - `close()`
+
+**Worlds**: `sqlite-provider { export types; export database; }` (this component)
+and `imports { import types; import database; }` (consumers).
+
+Defaults applied by `open` when options are omitted: `journal_mode=DELETE`,
+`synchronous=FULL`, `foreign_keys=ON`, `busy_timeout=5000`. `open` verifies the
+journal mode SQLite reports matches the request and fails otherwise.
+
+## Persistence model
+
+- **Rollback journal, not WAL.** WAL requires shared memory and file locks; the
+  WASI filesystem offers neither. `sqlite3.c` is compiled with
+  `-DSQLITE_OMIT_WAL`, so `PRAGMA journal_mode=WAL` is a silent no-op and the
+  connection stays on `delete`. Offered modes: `delete` (default), `persist`,
+  `memory` (tests only).
+- **`synchronous=FULL` by default** (`-DSQLITE_DEFAULT_SYNCHRONOUS=2` and set
+  again at open). Every commit fsyncs the journal and the database through
+  `wasi:filesystem/types.descriptor.sync`. `normal` is available via
+  `open-options` for lower-durability workloads.
+- **Single writer.** The VFS does no locking. One connection per file inside
+  the component, and one component instance per file on the host — the
+  wasmCloud plugin enforces `replicas: 1` for actor workloads
+  (`WASMCLOUD_ACTORS_REPLICA_CONSTRAINT`).
+- **Paths are guest paths inside a preopen.** The Kubernetes manifest mounts a
+  PVC at `mountPath` (default `/data/actors`) and exposes the same path to the
+  guest; open `/data/actors/<db>.sqlite`. Paths outside any preopen fail with
+  `open-failed`.
+- **No temp files.** `-DSQLITE_TEMP_STORE=3` and `-DSQLITE_STMTJRNL_SPILL=-1`
+  keep temp tables, sorters and statement journals in memory.
+
+### The VFS (`csrc/wasi-vfs.c`)
+
+`libsqlite3-sys` ships a `wasm32-wasi-vfs` feature whose C file is a 2010-era
+copy of SQLite's `demovfs.c`. It is **not** used here because:
+
+1. its `xFileControl` returns `SQLITE_OK` for every opcode; since SQLite 3.7.x
+   `PRAGMA` first asks the VFS via `SQLITE_FCNTL_PRAGMA`, and an `OK` answer
+   means "handled" — so *every PRAGMA becomes a no-op* (`journal_mode`,
+   `synchronous`, `user_version`, ...);
+2. `xTruncate` is a no-op (unsafe for any journal mode but DELETE; VACUUM never
+   shrinks the file);
+3. `xRandomness` returns no entropy; `xDelete` scans past the end of its buffer.
+
+`csrc/wasi-vfs.c` is the same public-domain design with those fixed
+(`SQLITE_NOTFOUND`, `ftruncate`, `getentropy`, `pread`/`pwrite`, ms-precision
+`xCurrentTimeInt64`) and is compiled by `build.rs` against
+`libsqlite3-sys`'s exported `sqlite3.h`. `sqlite3.c` is built with
+`-DSQLITE_OS_OTHER=1` so it calls our `sqlite3_os_init`. `make smoke` asserts
+that `PRAGMA journal_mode` really returns `delete` and that no `-wal` or stale
+`-journal` file is left behind.
+
+## Consuming from the JS component
+
+1. **WIT**: copy `wit/world.wit` to
+   `cli-extensions/packages/di-framework-cli-plugin-platform/assets/wit/deps/di-framework-sqlite/package.wit`
+   and add `import di-framework:sqlite/database@0.1.0;` to the generated guest
+   world (`sqliteProjectRequirements()` in `src/wit.ts` does this).
+2. **JS**: `componentize-qjs`/jco expose the import as an ES module:
+
+   ```ts
+   import { open } from 'di-framework:sqlite/database@0.1.0';
+
+   const db = open('/data/actors/orders.sqlite', undefined); // options optional
+   db.exec('CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT NOT NULL)');
+   db.run('INSERT OR REPLACE INTO kv VALUES (?1, ?2)', [
+     { tag: 'text', val: 'a' },
+     { tag: 'text', val: JSON.stringify({ n: 1 }) },
+   ]);
+   const row = db.first('SELECT v FROM kv WHERE k = ?1', [{ tag: 'text', val: 'a' }]);
+   // row: [['v', { tag: 'text', val: '{"n":1}' }]] | undefined
+
+   db.begin(undefined);            // BEGIN IMMEDIATE
+   try { /* ... */ db.commit(); } catch (e) { db.rollback(); throw e; }
+   ```
+
+   `result<_, error>` failures surface as thrown `ComponentError`s whose
+   `payload` is the `error` variant (`{ tag: 'execution-failed', val: { code, extendedCode, message } }`).
+   `integer` values are `bigint`s. A `MigrationDatabase.transaction(fn)` wrapper
+   maps to `begin`/`commit`/`rollback` (or `savepoint` when already inside one).
+3. **Compose** after componentize:
+
+   ```sh
+   scripts/compose.sh path/to/app.wasm path/to/app.composed.wasm  # = wac plug --plug dist/di-framework-sqlite.wasm app.wasm -o ...
+   ```
+
+   `wac plug` connects every export of the provider to the matching import of
+   the app; the composed component keeps only `wasi:*`/`wasmcloud:*` imports
+   for the host. `compose.sh` fails if `di-framework:sqlite/database` is still
+   imported afterwards.
+4. **Ship the artifact**: the plugin package build runs `make publish-asset`,
+   which builds the provider from source and copies the WASM, recovered WIT,
+   build metadata, and checksums into
+   `cli-extensions/packages/di-framework-cli-plugin-platform/dist/assets/sqlite/`. These generated
+   files ship in the npm package and are ignored by Git. No prebuilt provider is
+   checked into the source tree.
+
+### WASI version note
+
+This component targets `wasm32-wasip2` (imports `wasi:*@0.2.9`), the only
+stable Rust component target. The plugin's JS component targets WASI 0.3.0.
+`wac plug` composes them fine — the composed component then imports both
+`wasi:filesystem@0.2.9` (for SQLite) and the 0.3.0 interfaces (for the app) —
+but the *host* must provide both. wasmtime does (p2 and p3 linkers coexist);
+verify this on the wasmCloud host version you deploy to. When a stable
+`wasm32-wasip3` Rust target lands, changing `RUST_TARGET` in
+`scripts/tool-versions.env` and `.cargo/config.toml` is the only change needed
+here.
+
+## Verification
+
+`make smoke` builds `tests/smoke-consumer` (a `wasip2` command component that
+imports the interface), composes it with the provider using the pinned `wac`,
+and runs it under `wasmtime run --dir <tmp>::/data`. It checks: pragma
+defaults (`delete`/FULL/foreign keys), WAL is compiled out, DDL via `exec`,
+all `value` kinds round-trip, `changes`/`last-insert-rowid`, error mapping
+(constraint code 19/1555, syntax → `invalid-sql`, arity → `invalid-params`,
+multi-statement → `invalid-sql`, `commit` without `begin` →
+`invalid-transaction-state`), transactions, savepoints and rollback, `close`,
+reopening read-only (`SQLITE_READONLY` = 8), `open-failed` for missing
+directories and paths outside the preopen, `:memory:`, and finally that the
+`.sqlite` file exists on the host with no `-journal`/`-wal` left over.
+
+## Known limitations / follow-ups
+
+- Synchronous interface (no `async func`/streams); fine for the small result
+  sets the framework issues, and matches `bun:sqlite`-style drivers.
+- `row` repeats column names per row; switch to a `{columns, rows}` record if
+  large result sets ever matter.
+- No prepared-statement cache across calls (each `run`/`query` prepares once).
+- `wasmtime` used by `make smoke` is not pinned by this package.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@di-framework/sqlite-component",
-  "version": "0.0.1",
-  "description": "Placeholder for the di-framework platform SQLite component.",
-  "type": "module",
+  "version": "6.0.1",
+  "private": false,
+  "description": "SQLite WebAssembly component (di-framework:sqlite@0.1.0) for platform guests.",
   "license": "(MIT OR Apache-2.0)",
   "author": "@di-framework Contributors",
   "repository": {
@@ -10,13 +10,19 @@
     "url": "https://github.com/di-framework/platform",
     "directory": "platform/sqlite-component"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts"
+  "bugs": {
+    "url": "https://github.com/di-framework/platform/issues"
   },
-  "files": ["src"],
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/di-framework/platform",
+  "files": [
+    "dist",
+    "README.md",
+    "wit"
+  ],
+  "scripts": {
+    "build": "make build",
+    "test": "bun test",
+    "smoke": "make smoke",
+    "publish-asset": "make publish-asset"
   }
 }

package/wit/world.wit

@@ -0,0 +1,211 @@
+package di-framework:sqlite@0.1.0;
+
+/// Types shared by the `database` interface.
+///
+/// Kept in a separate interface (mirroring `wasmcloud:postgres/types`) so that
+/// values and errors unify when a consumer and a provider are composed with
+/// WAC, and so a future `prepared` or `async` interface can reuse them.
+interface types {
+  /// A structured error reported by SQLite itself.
+  record sqlite-error {
+    /// Primary SQLite result code (e.g. `19` = SQLITE_CONSTRAINT).
+    code: s32,
+    /// Extended result code (e.g. `2067` = SQLITE_CONSTRAINT_UNIQUE).
+    /// Equal to `code` when SQLite provides no extended information.
+    extended-code: s32,
+    /// Human-readable message from `sqlite3_errmsg`.
+    message: string,
+  }
+
+  /// Errors raised by functions in this package. Intentionally non-exhaustive:
+  /// consumers must keep a catch-all arm.
+  variant error {
+    /// The database file could not be opened or created. The guest path must
+    /// live under a directory the host has preopened (a mounted volume).
+    open-failed(string),
+    /// The connection has been closed with `close` and cannot be used again.
+    closed,
+    /// The statement could not be prepared: syntax error, unknown table or
+    /// column, or more than one statement passed to `run`/`query`/`first`.
+    invalid-sql(string),
+    /// Wrong number of parameters or a value that could not be bound.
+    invalid-params(string),
+    /// SQLite failed while executing a prepared statement (constraint
+    /// violation, read-only database, I/O error, ...). Branch on
+    /// `sqlite-error.code` / `extended-code` for machine-readable handling.
+    execution-failed(sqlite-error),
+    /// A column value could not be converted into a `value` (e.g. TEXT that is
+    /// not valid UTF-8).
+    value-conversion-failed(string),
+    /// The database file is locked or busy after the configured busy timeout.
+    /// With the WASI VFS this can only arise from another connection *inside
+    /// the same component instance*; the VFS does not perform file locking.
+    busy,
+    /// `begin`, `commit`, `rollback` (or a savepoint call) was issued in a
+    /// state that does not permit it (e.g. `commit` with no open transaction).
+    invalid-transaction-state(string),
+    /// Any other implementation-specific failure.
+    other(string),
+  }
+
+  /// A dynamically-typed SQLite value, used for parameters and results.
+  variant value {
+    null,
+    integer(s64),
+    real(f64),
+    text(string),
+    blob(list<u8>),
+  }
+
+  /// A result row: `(column-name, value)` pairs in column order. Column names
+  /// are repeated per row on purpose: result sets in the framework (actor
+  /// state, queue jobs, migration bookkeeping) are small and JS consumers turn
+  /// each row straight into an object.
+  type row = list<tuple<string, value>>;
+
+  /// `PRAGMA synchronous` level. `full` is the default and is what the
+  /// framework expects for durable actor / queue state; `normal` trades a
+  /// small durability window (power loss mid-commit) for fewer fsyncs. `off`
+  /// exists for tests only.
+  enum sync-mode {
+    off,
+    normal,
+    full,
+  }
+
+  /// Rollback-journal mode. WAL is intentionally not offered: the WASI VFS
+  /// has neither file locking nor shared memory, both of which WAL needs, and
+  /// SQLite is compiled with `SQLITE_OMIT_WAL`. `delete` is the default and
+  /// the safest choice on WASI preopens (the journal is unlinked after every
+  /// commit); `persist` keeps the journal file and zeroes its header; `memory`
+  /// is for tests only. TRUNCATE is deliberately left out of the surface.
+  enum journal-mode {
+    delete,
+    persist,
+    memory,
+  }
+
+  /// How `begin` acquires its lock. Maps to `BEGIN DEFERRED|IMMEDIATE|EXCLUSIVE`.
+  enum transaction-behavior {
+    deferred,
+    immediate,
+    exclusive,
+  }
+
+  /// Options accepted by `open`. Every field is optional; `none` means the
+  /// documented default.
+  record open-options {
+    /// Create the database file if it does not exist. Default: true.
+    create: option<bool>,
+    /// Open read-only. Default: false.
+    read-only: option<bool>,
+    /// `PRAGMA synchronous`. Default: `full`.
+    synchronous: option<sync-mode>,
+    /// `PRAGMA journal_mode`. Default: `delete`.
+    journal-mode: option<journal-mode>,
+    /// `PRAGMA busy_timeout` in milliseconds. Default: 5000.
+    busy-timeout-ms: option<u32>,
+    /// `PRAGMA foreign_keys`. Default: true.
+    foreign-keys: option<bool>,
+  }
+}
+
+/// Synchronous, single-writer SQLite access backed by the WASI filesystem.
+///
+/// The implementer of this interface is the `di-framework:sqlite` Rust
+/// component. It bundles SQLite (amalgamation) with a minimal WASI VFS: no
+/// file locking, no mmap, no WAL, in-memory temp store. Consequently exactly
+/// one component instance may own a given database file at a time; the
+/// framework enforces `replicas: 1` for actor workloads for this reason.
+///
+/// Paths are guest paths. The host mounts a volume at `mountPath` and the same
+/// string is the guest-visible directory (a WASI preopen), e.g.
+/// `/data/actors/orders/order-42.sqlite`.
+interface database {
+  use types.{error, value, row, open-options, transaction-behavior};
+
+  /// Open (and by default create) the database at `path`, applying the
+  /// pragmas described in `open-options` (rollback journal, `synchronous=FULL`,
+  /// `foreign_keys=ON`, 5 s busy timeout when `options` is `none`). Use
+  /// `:memory:` for an in-memory database.
+  open: func(path: string, options: option<open-options>) -> result<connection, error>;
+
+  /// The bundled SQLite library version, e.g. `3.53.2`.
+  sqlite-version: func() -> string;
+
+  /// An open SQLite connection. Dropping the resource closes it; an open
+  /// transaction is rolled back by SQLite in that case.
+  resource connection {
+    /// Execute one or more `;`-separated statements without parameters and
+    /// discard any results. Intended for DDL / migrations / pragmas. Untrusted
+    /// input must never be interpolated into `sql`.
+    exec: func(sql: string) -> result<_, error>;
+
+    /// Execute a single parameterized statement and return the number of rows
+    /// changed (`sqlite3_changes`). Parameters bind positionally to `?`/`?NNN`.
+    /// Statements that return rows (e.g. `INSERT ... RETURNING`) run to
+    /// completion; their rows are discarded.
+    run: func(sql: string, params: list<value>) -> result<u64, error>;
+
+    /// Execute a single parameterized statement and return all rows.
+    query: func(sql: string, params: list<value>) -> result<list<row>, error>;
+
+    /// Execute a single parameterized statement and return only the first row,
+    /// or `none` when the statement produced no rows.
+    first: func(sql: string, params: list<value>) -> result<option<row>, error>;
+
+    /// `BEGIN [DEFERRED|IMMEDIATE|EXCLUSIVE]`. Default: `immediate`, which is
+    /// the right choice for a single-writer file with no lock arbitration.
+    /// Fails with `invalid-transaction-state` if a transaction is already open;
+    /// nest with `savepoint` instead.
+    begin: func(behavior: option<transaction-behavior>) -> result<_, error>;
+
+    /// `COMMIT` the open transaction.
+    commit: func() -> result<_, error>;
+
+    /// `ROLLBACK` the open transaction.
+    rollback: func() -> result<_, error>;
+
+    /// `SAVEPOINT <name>`; usable for nested transactions. `name` must match
+    /// `[A-Za-z_][A-Za-z0-9_]*`.
+    savepoint: func(name: string) -> result<_, error>;
+
+    /// `RELEASE SAVEPOINT <name>`.
+    release-savepoint: func(name: string) -> result<_, error>;
+
+    /// `ROLLBACK TO SAVEPOINT <name>` followed by `RELEASE`, so the savepoint
+    /// is fully unwound.
+    rollback-to-savepoint: func(name: string) -> result<_, error>;
+
+    /// True while a transaction (or savepoint) is open on this connection.
+    in-transaction: func() -> bool;
+
+    /// Rows changed by the most recent `run`/`exec`.
+    changes: func() -> u64;
+
+    /// `sqlite3_last_insert_rowid`.
+    last-insert-rowid: func() -> s64;
+
+    /// Explicitly close the connection. Subsequent calls fail with `closed`.
+    close: func() -> result<_, error>;
+  }
+}
+
+/// The world implemented by the Rust component. WASI imports (filesystem,
+/// clocks, cli, io) are pulled in by the Rust `wasm32-wasip2` target and
+/// therefore do not need to be listed here. `types` is exported explicitly so
+/// the component is self-contained: without it WIT elaboration would turn the
+/// `use types.{...}` into an *import* of `types`, which `wac plug` could not
+/// satisfy from this component.
+world sqlite-provider {
+  export types;
+  export database;
+}
+
+/// The world a consumer (e.g. the componentize-qjs JS component) targets when
+/// it wants a SQLite database. `wac plug` satisfies these imports with the
+/// `sqlite-provider` component's exports.
+world imports {
+  import types;
+  import database;
+}

package/src/index.ts

@@ -1,2 +0,0 @@
-/** Placeholder. Implementation ships from di-framework/platform. */
-export const name = "@di-framework/sqlite-component" as const;