acrylblends 0.7.7 → 0.7.8

package/docs/framework/agents/index.md

@@ -5,14 +5,29 @@ A coding agent (Claude Code, Codex, OpenCode, Copilot and others) builds on Acry
 
 - `docs/framework/`: these pages. Start at `README.md`; `api/summary.md` is the one-page summary of the API.
 - `AGENTS.md`: where the API is, how a feature is built (an `Acryl` app mounted with `ctx.router.route`, a plugin registered in `src/app.ts` and `blend.yaml`, a state cell),
-  the things that surprise people, and what must pass before a task is done (`npm test` and `npm run check`).
-- `CLAUDE.md`: one line, `@AGENTS.md`, so tools that read `CLAUDE.md` read the same guide.
+  the defaults and how each is swapped, the things that surprise people, and what must pass before a task is done (`npm test` and `npm run check`).
+- `CLAUDE.md`: the same text as `AGENTS.md`, so tools that read either file read the same guide.
+- One skill, `app-guide`, in `.claude/skills/app-guide/SKILL.md` and `.agents/skills/app-guide/SKILL.md` (the same text): where to read first, the one plugin folder, the defaults, the door, and what "done" means.
+- `.gitignore` lists `.acryl/`, the folder the door keeps its secret and state in, so `git add -A` stages none of it.
+
+## One plugin folder
+
+Every plugin of an app is a folder in `plugins/<name>/`, at the root of the app: the library plugins `acrylblends add <name>` copies (listed in `plugins/library.json`), and the
+plugins you or an agent write. There is no `src/plugins/` and no `extensions/`. An app made before this layout keeps working for one release: the CLI reads its `src/plugins/` and
+`extensions/` and warns; move them with `git mv src/plugins plugins`, fix the paths in `tsconfig.json`, `package.json` and `src/`, and `git mv extensions/<name> plugins/<name>`.
+
+## Defaults, and how to swap each
+
+The framework is not rigid: every choice is a plugin behind a port, and the default is only a fallback. A new app names each default in `AGENTS.md`: records on the `db` port
+with SQLite, small state on the `kv` port with one JSON file, the Node server, the browser as the window (`acrylblends add desktop` adds Electron), browser code through
+`clientModules`. A swap changes the one file that opens or mounts the choice (the opener, `src/db.ts`; or `src/app.ts` in a Blend app), because nothing else imports a provider
+(`acrylblends check-deps` checks it). An outside tool, such as a database server or a bundler, joins the app as a provider in `plugins/<name>/` that implements the port.
 
 ## What an agent can do inside a running app
 
 The `acryl-app` template (a Cordis app) also lets an agent change the app while it runs:
 
-1. The agent writes a plugin into `extensions/<name>/index.ts`. The plugin may import `acrylblends` and the other subpaths by name.
+1. The agent writes a plugin into `plugins/<name>/index.ts`. The plugin may import `acrylblends` and the other subpaths by name.
 2. The app installs it as a child plugin, runs its `check(ctx)` with the plugin's own context, and keeps the previous version if the new one fails to start or to pass its check.
 3. A plugin's routes are an `Acryl` app mounted with `ctx.router.route`, so removing the plugin removes its routes.
 

package/docs/framework/getting-started/desktop.md

@@ -16,11 +16,11 @@ npm run desktop
 ```
 
 In a Blend app, the same two commands (`npx acrylblends add desktop`, `npm install`) add the Blend form of the shell, and `npx acrylblends init my-app --template todo --desktop` creates a Blend app with it already in.
-`acrylblends add desktop` chooses the right form: a Blend app (it has `src/plugins/instance`) or a plain Acryl app.
+`acrylblends add desktop` chooses the right form: a Blend app (it has `plugins/instance`) or a plain Acryl app.
 
 ## What it adds
 
-- `src/plugins/desktop-web/` (a plain app) or `src/plugins/desktop/` (a Blend app): the window code. Only this folder imports `electron`; the app's own code never does.
+- `plugins/desktop-web/` (a plain app) or `plugins/desktop/` (a Blend app): the window code. Only this folder imports `electron`; the app's own code never does.
 - `electron` as a development dependency (pinned to 44.9.3) and the script `npm run desktop`.
 - `.acrylblends/` in `.gitignore`: Electron's user data (window state, cache, logs) lives in `.acrylblends/electron` inside the app's own folder, never in the user's application-data folder.
 

package/docs/framework/guides/client-modules.md

@@ -149,8 +149,9 @@ For a request that streams its answer and a Stop button (an `AbortController` ke
 - JSX in a client module always compiles for the DOM renderer (`acrylblends/jsx/dom`), whatever the server's `tsconfig.json` says. A file's
   own `/** @jsxImportSource ... */` comment still wins.
 - `acrylblends/jsx/dom`, its `jsx-runtime`, `jsx-dev-runtime` and `client` are one browser module (`@acrylblends/jsx-dom.js`), and
-  `acrylblends/client` is another (`@acrylblends/client.js`). Neither imports anything. The same app serves them, and each import is
-  rewritten to a URL relative to the module, so the setup works under whatever path you route `clientModules` at.
+  `acrylblends/client` is another (`@acrylblends/client.js`), and `acrylblends/read-sse` (the reader of a POST event stream, see
+  [Streaming](../helpers/streaming.md#reading-a-post-event-stream-in-the-browser)) a third (`@acrylblends/read-sse.js`). None imports anything. The same app
+  serves them, and each import is rewritten to a URL relative to the module, so the setup works under whatever path you route `clientModules` at.
 - Import your own modules with their file names, as the browser fetches them: `import { label } from './parts/label.ts'`.
 - Another package (`import confetti from 'canvas-confetti'`) is left as it is: add an
   [import map](https://developer.mozilla.org/docs/Web/HTML/Element/script/type/importmap) to the page for it, or use a bundler.
@@ -185,7 +186,7 @@ Compile the client folder once when you build, as the `build` script of your `pa
 }
 ```
 
-It writes each module compiled to `dist/client` at the same path and file name, so the page's URLs stay the same, and copies the two
+It writes each module compiled to `dist/client` at the same path and file name, so the page's URLs stay the same, and copies the three
 browser modules to `dist/client/@acrylblends/`. Run it where `typescript` is installed, before the development dependencies are removed.
 
 With `NODE_ENV=production` and the `compiled` option set, `clientModules` serves only that folder and compiles nothing. A module that is in

package/docs/framework/guides/data.md

@@ -2,16 +2,16 @@
 
 An app that keeps records (users, notes, orders) keeps them in a SQL database, and reaches it through one small interface, `db`. Handlers and
 stores take a `Db` as an argument and never import a driver, so the file or server behind it can change without touching them. SQLite is the
-provider today; a Postgres provider (Postgres or Supabase through `DATABASE_URL`) is planned and serves the same interface.
+provider in `acrylblends`. Postgres (or Supabase, through `DATABASE_URL`) is an optional plugin, `acryl-db-postgres`, that serves the same
+interface; it is not part of `acrylblends` or the templates, and an app adds it only when it must use Postgres.
 
 ## Choosing
 
 | The app | Use | State |
 | --- | --- | --- |
 | Normal web or desktop app, users, lists, orders | `db` with SQLite (the `notes` and `chat` templates) | available |
-| Hosted, many users | `db` with Postgres or Supabase | planned |
+| Must use Postgres or Supabase | `db` with the optional `acryl-db-postgres` plugin | optional, not in `acrylblends` |
 | Tiny, one person, a few screens | [`kv`](#a-tiny-app-kv), named JSON documents with no SQL | available |
-| Agents or long tasks that must survive a restart | `durable`, in the same database as `db` | planned |
 
 Start with `db` when the data has users, lists or relations: SQL is what people and coding agents already know. Start with `kv` when the whole
 data is a handful of settings or a small list that one process reads and writes.
@@ -190,7 +190,7 @@ await db.transaction(async (tx) => {
 
 ## Writing SQL that moves to Postgres
 
-The Postgres provider is not released yet, and it will serve the same interface. SQL that stays inside this list runs on both:
+The optional Postgres plugin serves the same interface. SQL that stays inside this list runs on both:
 
 - Placeholders are `?` on every provider.
 - Use `RETURNING` to get a new row, not a driver-specific "last id".
@@ -269,8 +269,8 @@ The rule is checked, not hoped for. The app names its opener once, in `package.j
 }
 ```
 
-`acrylblends check-deps` reads every `.ts`, `.tsx` and `.js` file in `src/`, `test/`, `tests/` and `extensions/`, and fails when a file other than
-the opener imports a database driver, an opener such as `acrylblends/db/sqlite` or `acryl-db-sqlite`, or (outside `src/plugins/desktop`) `electron`.
+`acrylblends check-deps` reads every `.ts`, `.tsx` and `.js` file in `src/`, `test/`, `tests/` and `plugins/`, and fails when a file other than
+the opener imports a database driver, an opener such as `acrylblends/db/sqlite` or `acryl-db-sqlite`, or (outside `plugins/desktop`) `electron`.
 It names the file and the line:
 
 ```

package/docs/framework/helpers/streaming.md

@@ -86,7 +86,7 @@ app.get('/sse', async (c) => {
 A reader that closes the tab, loses the network or presses a Stop button should not leave your server working for nobody (a request to a paid model, a database scan). There are two signals, and they are not the same:
 
 - **`c.req.raw.signal`** is the request's `AbortSignal`. It aborts when the client goes away. Pass it to anything that takes a `signal`, such as `fetch`, and the work stops with the client. This is the one to use for cancelling work.
-- **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled. Measured: when you call `app.request()` with a `signal` and abort it, `c.req.raw.signal` aborts and `stream.aborted` stays `false`; when the reader of the response body is cancelled, `stream.onAbort` fires and `c.req.raw.signal` does not. On a real connection the request signal is what fired when a browser aborted its `fetch`. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
+- **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled, and they are set when the response body is cancelled, which is what the Node adapter does when the connection closes. Over a real connection, a browser that aborts its `fetch` (or closes the tab) fires both: the request signal and `stream.onAbort`. Under `app.request()` (in-process, no socket) they come apart, and this is how the upstream behaves too: aborting the `signal` you passed to `app.request()` fires `c.req.raw.signal` while `stream.aborted` stays `false`, and cancelling the reader of the response body fires `stream.onAbort` while `c.req.raw.signal` does not. A test that simulates the client leaving therefore aborts the request signal (for work cancelled through the signal) or cancels the body reader (for `stream.onAbort`), whichever the handler listens to. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
 
 An abort event that has already fired does not fire again, so check `signal.aborted` before you wait for it:
 
@@ -160,31 +160,10 @@ app.post('/api/chat', async (c) => {
 
 ## Reading a POST event stream in the browser
 
-`EventSource` can only send a GET request. For a POST (a chat message), read the response body yourself; this function calls `on` for each event as it arrives:
+`EventSource` can only send a GET request. For a POST (a chat message), call `fetch` and read the events with `readSSE` from `acrylblends/read-sse`. It is an async iterator over the events of a `text/event-stream` response, parsed by the rules of the SSE standard (LF, CRLF and CR line ends, several `data` lines joined with a line feed, comments, UTF-8 split across chunks):
 
 ```ts
-async function readEvents(body: ReadableStream<Uint8Array>, on: (event: string, data: string) => void): Promise<void> {
-  const reader = body.getReader()
-  const decoder = new TextDecoder()
-  let buffer = ''
-  for (;;) {
-    const { done, value } = await reader.read()
-    if (done) return
-    // Line endings may be CRLF; a \r at the end of a chunk is completed by the next chunk, so normalise the whole buffer.
-    buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n')
-    const blocks = buffer.split('\n\n')
-    buffer = blocks.pop() ?? ''
-    for (const block of blocks) {
-      let event = 'message'
-      const data: string[] = []
-      for (const line of block.split('\n')) {
-        if (line.startsWith('event:')) event = line.slice(6).trim()
-        else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')) // the SSE spec strips one leading space only
-      }
-      on(event, data.join('\n'))
-    }
-  }
-}
+import { readSSE } from 'acrylblends/read-sse'
 
 const controller = new AbortController() // controller.abort() is the Stop button
 const response = await fetch('/api/chat', {
@@ -193,13 +172,19 @@ const response = await fetch('/api/chat', {
   body: JSON.stringify({ message: 'Hello' }),
   signal: controller.signal,
 })
+
 let answer = ''
-await readEvents(response.body!, (event, data) => {
+for await (const { event, data } of readSSE(response)) {
   if (event === 'token') answer += JSON.parse(data) as string
-})
+}
 ```
 
-A complete chat component built on this is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
+- Each event is `{ event, data, id?, retry? }`; `event` is `message` when the server named none, and `data` is a string (parse it yourself when the server sends JSON).
+- Leaving the loop early (a `break`, a thrown error) cancels the response body, so the request to the server ends. Abort the `fetch` with its own `signal` for a Stop button; `readSSE(response, { signal })` also stops reading when a signal aborts.
+- A response that is not `ok` throws with its status (the body is not parsed as events), and a response without a body throws.
+- A client module served by `clientModules` can import it as it is (`import { readSSE } from 'acrylblends/read-sse'`): the import is pointed at a browser file the same app serves, like `acrylblends/client`. With a bundler it is an ordinary import.
+
+A complete chat component is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
 
 ## Error Handling
 

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "files": 99,
-  "digest": "sha256:075d537930a53f7ba46b989ff82f9d83a720270c60d848917e6501bfabff6df1"
+  "digest": "sha256:9b0fe3329319398ce1108a015a99247c001b02cfb30a953b4b180a73674e2aec"
 }

package/lib/browser/read-sse.js

@@ -0,0 +1,84 @@
+//#region ../../plugins/acryl-router/src/helpers/read-sse.ts
+/**
+* Read the events of a `text/event-stream` response as they arrive. Leaving the loop early (`break`, a thrown error) cancels the body, so the
+* request to the server ends.
+* @throws when the response is not `ok` (the status is in the message; the body is cancelled, not parsed), has no body, or fails while it is read.
+*/
+async function* readSSE(response, options = {}) {
+	if (!response.ok) {
+		await response.body?.cancel().catch(() => void 0);
+		throw new Error(`readSSE: the request failed with ${String(response.status)}${response.statusText === "" ? "" : ` ${response.statusText}`}`);
+	}
+	if (response.body === null) throw new Error("readSSE: the response has no body to read");
+	const { signal } = options;
+	if (signal?.aborted === true) {
+		await response.body.cancel().catch(() => void 0);
+		return;
+	}
+	const reader = response.body.getReader();
+	const onAbort = () => {
+		reader.cancel().catch(() => void 0);
+	};
+	signal?.addEventListener("abort", onAbort, { once: true });
+	const decoder = new TextDecoder("utf-8");
+	let buffer = "";
+	let skipLineFeed = false;
+	let name = "";
+	let data = [];
+	let id;
+	let retry;
+	/** Apply one line; returns the event when this line completes one. */
+	const apply = (line) => {
+		if (line === "") {
+			const event = data.length === 0 ? void 0 : {
+				event: name === "" ? "message" : name,
+				data: data.join("\n"),
+				...id === void 0 ? {} : { id },
+				...retry === void 0 ? {} : { retry }
+			};
+			name = "";
+			data = [];
+			id = void 0;
+			retry = void 0;
+			return event;
+		}
+		if (line.startsWith(":")) return void 0;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		if (field === "event") name = value;
+		else if (field === "data") data.push(value);
+		else if (field === "id") {
+			if (!value.includes("\0")) id = value;
+		} else if (field === "retry" && /^\d+$/u.test(value)) retry = Number(value);
+	};
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			let text = decoder.decode(value, { stream: true });
+			if (skipLineFeed && text.startsWith("\n")) text = text.slice(1);
+			if (text !== "") skipLineFeed = false;
+			buffer += text;
+			let start = 0;
+			for (let index = 0; index < buffer.length; index += 1) {
+				const code = buffer.charCodeAt(index);
+				if (code !== 10 && code !== 13) continue;
+				const line = buffer.slice(start, index);
+				if (code === 13) if (index + 1 < buffer.length) {
+					if (buffer.charCodeAt(index + 1) === 10) index += 1;
+				} else skipLineFeed = true;
+				start = index + 1;
+				const event = apply(line);
+				if (event !== void 0) yield event;
+			}
+			buffer = buffer.slice(start);
+		}
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		await reader.cancel().catch(() => void 0);
+	}
+}
+//#endregion
+export { readSSE };

package/lib/db/sqlite.d.ts

@@ -1,4 +1,4 @@
-import { n as DbExecutor, r as SqlValue, t as Db } from "../database-D_UN6We8.js";
+import { c as DbExecutor, l as SqlValue, s as Db } from "../index-D4FAsBZu.js";
 
 //#region ../../plugins/acryl-db-sqlite/src/open.d.ts
 interface OpenDbOptions {

package/lib/db.d.ts

@@ -1,85 +1,2 @@
-//#region ../../plugins/acryl-db/src/facade/database.d.ts
-/** Values supported by the portable SQL drivers. */
-type SqlValue = null | number | bigint | string | Uint8Array;
-/**
- * Asynchronous SQL operations shared by a database and its transaction handles.
- *
- * `exec` runs SQL text without bindings and may contain several statements. `run`, `get`, and `all`
- * execute one statement with positional bindings. Adapters may cache prepared statements by SQL text,
- * so callers pass values as bindings instead of interpolating them. `run` resolves the number of rows
- * the statement changed.
- */
-interface DbExecutor {
-  exec(sql: string): Promise<void>;
-  run(sql: string, ...params: SqlValue[]): Promise<{
-    readonly changes: number;
-  }>;
-  get<T extends object>(sql: string, ...params: SqlValue[]): Promise<T | undefined>;
-  all<T extends object>(sql: string, ...params: SqlValue[]): Promise<T[]>;
-}
-/**
- * Minimal portable SQL database facade.
- *
- * All operations are asynchronous so adapters may execute outside the caller's runtime.
- *
- * `transaction` passes the callback a transaction handle. All work in the transaction
- * must use that handle; the handle is invalid after the callback settles. Adapters must
- * queue unrelated operations and other transactions until the transaction finishes. The
- * returned promise settles after commit or rollback. Calling the database itself (including
- * `transaction`) from inside a callback therefore waits for that transaction and
- * never settles.
- *
- * When the callback rejects, the adapter must roll the transaction back before rejecting
- * with that same error. If rollback fails, it must reject with a different error (for
- * example an `AggregateError`) so callers cannot mistake the callback error for a
- * guaranteed rollback.
- *
- * Closing is the adapter's: the plugin that opened a database closes it, so the facade an
- * app receives has no `close`.
- */
-interface Db extends DbExecutor {
-  transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T>;
-}
-//#endregion
-//#region ../../plugins/acryl-db/src/facade/migrations.d.ts
-type Migration = {
-  readonly version: number;
-  readonly statements: readonly string[];
-};
-/**
- * Apply all pending migrations atomically, tracking their version in the named metadata table.
- *
- * The bookkeeping SQL runs unchanged on SQLite and Postgres: no `STRICT` table, `ON CONFLICT DO NOTHING`
- * instead of `INSERT OR IGNORE`, and the version written as a checked integer rather than a binding,
- * since the two dialects spell placeholders differently.
- */
-declare function applyMigrations(database: Db, migrations: readonly Migration[], options: {
-  readonly table: string;
-}): Promise<void>;
-//#endregion
-//#region ../../plugins/acryl-db/src/facade/schema.d.ts
-/** Validate a prefix before using it as part of a SQL identifier. */
-declare function validateSchemaPrefix(prefix: string): void;
-//#endregion
-//#region ../../plugins/acryl-db/src/migration-files.d.ts
-/**
- * Read every `NNN-name.sql` file of a folder, in number order.
- * @throws when a `.sql` file is not named `NNN-name.sql`, or the numbers do not run 1, 2, 3, ... without gaps or repeats.
- */
-declare function readMigrationFiles(folder: string | URL): Promise<Migration[]>;
-//#endregion
-//#region ../../plugins/acryl-db/src/index.d.ts
-/**
- * The `db` port: what an app's code sees of its relational database, whichever provider (`acryl-db-sqlite`, `acryl-db-postgres`) serves
- * it. Plain code (an acrylblends app) opens a database with a provider's `openDb`; a Cordis plugin declares `inject: ['db']`, imports
- * `acryl-db/cordis` for the `ctx.db` type, and never imports a driver.
- *
- * Bindings are positional `?` placeholders on every provider; a provider whose database spells them differently translates them.
- * This entry imports nothing from Cordis, at runtime or in its types.
- */
-/** The service name every `db` provider registers. */
-declare const DB_SERVICE = "db";
-/** The table that records an app's migration version. */
-declare const MIGRATIONS_TABLE = "_migrations";
-//#endregion
+import { a as Migration, c as DbExecutor, i as validateSchemaPrefix, l as SqlValue, n as MIGRATIONS_TABLE, o as applyMigrations, r as readMigrationFiles, s as Db, t as DB_SERVICE } from "./index-D4FAsBZu.js";
 export { DB_SERVICE, type Db, type DbExecutor, MIGRATIONS_TABLE, type Migration, type SqlValue, applyMigrations, readMigrationFiles, validateSchemaPrefix };

package/lib/index-BLTYsyc1.d.ts

@@ -0,0 +1,93 @@
+//#region ../../plugins/acryl-kv/src/kv.d.ts
+/** `T`, except a promise: the callback of `update` is synchronous, and an async one is a type error. */
+type NotPromise<T> = T extends PromiseLike<unknown> ? never : T;
+/** Anything JSON can hold. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * Named JSON documents. Every call returns a promise, so a file, SQLite and Postgres answer alike.
+ *
+ * Keys are non-empty strings. Values are JSON: `undefined`, functions, symbols, bigints and non-finite numbers are refused with a
+ * `TypeError` before anything is written, and a value read back is a copy.
+ *
+ * There is no `close`: the code that opened a store closes it (see {@link KvOpened}), so a plugin cannot close the store another uses.
+ */
+interface Kv {
+  /** The value stored under the key, or `undefined`. */
+  get<T = JsonValue>(key: string): Promise<T | undefined>;
+  /** Store a value under the key, replacing any. Resolves once it is durable. */
+  set<T = JsonValue>(key: string, value: T): Promise<void>;
+  /**
+   * Replace the value under the key by `change(current)`, atomically: `current` is `undefined` when the key is missing, `change` is
+   * synchronous (an `async` function is a type error, and a returned promise is rejected at run time: read what you need first, then update), and no other write to the key happens between reading it and writing the result. Resolves the new value. A `change` that
+   * throws, or returns something that is not JSON, leaves the value as it was and rejects with its error.
+   */
+  update<T = JsonValue>(key: string, change: (current: T | undefined) => NotPromise<T>): Promise<T>;
+  /** Remove the key. A missing key is not an error. */
+  delete(key: string): Promise<void>;
+  /** The keys that start with the prefix (all of them without one), sorted by code point (the order of their UTF-8 bytes, not of UTF-16 units). */
+  list(prefix?: string): Promise<string[]>;
+}
+/** An open store and the one function that closes it. */
+interface KvOpened {
+  readonly kv: Kv;
+  /** Waits for the writes in flight, then releases the storage. Calling it again does nothing; calls on `kv` after it reject. */
+  close(): Promise<void>;
+}
+//#endregion
+//#region ../../plugins/acryl-kv/src/check.d.ts
+/**
+ * What every `kv` provider checks the same way, so a bad call fails alike on a file and on SQL: the key, the value, and the order of keys.
+ */
+/** A key is a non-empty string. */
+declare function checkKey(key: unknown): asserts key is string;
+/**
+ * The JSON text of a value. `undefined`, functions, symbols, bigints, circular structures and non-finite numbers (which JSON would turn
+ * into `null`) are refused with a `TypeError`; nothing is stored for them.
+ */
+declare function encodeValue(value: unknown): string;
+/** The value of stored JSON text: a new copy each time, so changing what `get` returned changes nothing stored. */
+declare function decodeValue<T>(text: string): T;
+/** Order two keys by code point (the order of UTF-8 bytes, which SQLite's binary collation and Postgres' "C" collation give too). */
+declare function compareKeys(a: string, b: string): number;
+/** The number of code points in a string (what SQL's `substr` counts). */
+declare function codePoints(text: string): number;
+/**
+ * Call an `update` callback and check what it returns: the callback is synchronous, so a promise (an `async` function the types should have
+ * refused) is rejected with a message that says what to do, instead of being stored as `{}`.
+ */
+declare function runChange<T>(change: (current: T | undefined) => T, current: T | undefined): T;
+//#endregion
+//#region ../../plugins/acryl-kv/src/copy.d.ts
+interface CopyKvOptions {
+  /** Replace keys the target already has. Without it, a shared key stops the copy before anything is written. */
+  readonly overwrite?: boolean;
+  /** Copy only the keys that start with this. */
+  readonly prefix?: string;
+}
+interface CopyKvResult {
+  /** Keys written to the target. */
+  readonly copied: number;
+  /** Of those, keys the target already had. */
+  readonly overwritten: number;
+}
+/**
+ * Copy every key of one store into another: the import when an app moves from a JSON file to SQL (the file opened with
+ * `acryl-kv-json` is the source, `kvOnDb` the target). The source is not changed.
+ * @throws when the target has a key the source has and `overwrite` is not set; nothing is written then.
+ */
+declare function copyKv(source: Kv, target: Kv, options?: CopyKvOptions): Promise<CopyKvResult>;
+//#endregion
+//#region ../../plugins/acryl-kv/src/index.d.ts
+/**
+ * The `kv` port: named JSON documents for an app too small for SQL, whichever provider serves it (`acryl-kv-json` for one file,
+ * `acryl-kv-db` over the `db` port). Plain code opens a store with a provider's `openKv`; a Cordis plugin declares `inject: ['kv']`, imports
+ * `acryl-kv/cordis` for the `ctx.kv` type, and never imports a provider.
+ *
+ * This entry imports nothing from Cordis, at runtime or in its types.
+ */
+/** The service name every `kv` provider registers. */
+declare const KV_SERVICE = "kv";
+//#endregion
+export { checkKey as a, decodeValue as c, JsonValue as d, Kv as f, copyKv as i, encodeValue as l, NotPromise as m, CopyKvOptions as n, codePoints as o, KvOpened as p, CopyKvResult as r, compareKeys as s, KV_SERVICE as t, runChange as u };

package/lib/index-D4FAsBZu.d.ts

@@ -0,0 +1,85 @@
+//#region ../../plugins/acryl-db/src/facade/database.d.ts
+/** Values supported by the portable SQL drivers. */
+type SqlValue = null | number | bigint | string | Uint8Array;
+/**
+ * Asynchronous SQL operations shared by a database and its transaction handles.
+ *
+ * `exec` runs SQL text without bindings and may contain several statements. `run`, `get`, and `all`
+ * execute one statement with positional bindings. Adapters may cache prepared statements by SQL text,
+ * so callers pass values as bindings instead of interpolating them. `run` resolves the number of rows
+ * the statement changed.
+ */
+interface DbExecutor {
+  exec(sql: string): Promise<void>;
+  run(sql: string, ...params: SqlValue[]): Promise<{
+    readonly changes: number;
+  }>;
+  get<T extends object>(sql: string, ...params: SqlValue[]): Promise<T | undefined>;
+  all<T extends object>(sql: string, ...params: SqlValue[]): Promise<T[]>;
+}
+/**
+ * Minimal portable SQL database facade.
+ *
+ * All operations are asynchronous so adapters may execute outside the caller's runtime.
+ *
+ * `transaction` passes the callback a transaction handle. All work in the transaction
+ * must use that handle; the handle is invalid after the callback settles. Adapters must
+ * queue unrelated operations and other transactions until the transaction finishes. The
+ * returned promise settles after commit or rollback. Calling the database itself (including
+ * `transaction`) from inside a callback therefore waits for that transaction and
+ * never settles.
+ *
+ * When the callback rejects, the adapter must roll the transaction back before rejecting
+ * with that same error. If rollback fails, it must reject with a different error (for
+ * example an `AggregateError`) so callers cannot mistake the callback error for a
+ * guaranteed rollback.
+ *
+ * Closing is the adapter's: the plugin that opened a database closes it, so the facade an
+ * app receives has no `close`.
+ */
+interface Db extends DbExecutor {
+  transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T>;
+}
+//#endregion
+//#region ../../plugins/acryl-db/src/facade/migrations.d.ts
+type Migration = {
+  readonly version: number;
+  readonly statements: readonly string[];
+};
+/**
+ * Apply all pending migrations atomically, tracking their version in the named metadata table.
+ *
+ * The bookkeeping SQL runs unchanged on SQLite and Postgres: no `STRICT` table, `ON CONFLICT DO NOTHING`
+ * instead of `INSERT OR IGNORE`, and the version written as a checked integer rather than a binding,
+ * since the two dialects spell placeholders differently.
+ */
+declare function applyMigrations(database: Db, migrations: readonly Migration[], options: {
+  readonly table: string;
+}): Promise<void>;
+//#endregion
+//#region ../../plugins/acryl-db/src/facade/schema.d.ts
+/** Validate a prefix before using it as part of a SQL identifier. */
+declare function validateSchemaPrefix(prefix: string): void;
+//#endregion
+//#region ../../plugins/acryl-db/src/migration-files.d.ts
+/**
+ * Read every `NNN-name.sql` file of a folder, in number order.
+ * @throws when a `.sql` file is not named `NNN-name.sql`, or the numbers do not run 1, 2, 3, ... without gaps or repeats.
+ */
+declare function readMigrationFiles(folder: string | URL): Promise<Migration[]>;
+//#endregion
+//#region ../../plugins/acryl-db/src/index.d.ts
+/**
+ * The `db` port: what an app's code sees of its relational database, whichever provider (`acryl-db-sqlite`, `acryl-db-postgres`) serves
+ * it. Plain code (an acrylblends app) opens a database with a provider's `openDb`; a Cordis plugin declares `inject: ['db']`, imports
+ * `acryl-db/cordis` for the `ctx.db` type, and never imports a driver.
+ *
+ * Bindings are positional `?` placeholders on every provider; a provider whose database spells them differently translates them.
+ * This entry imports nothing from Cordis, at runtime or in its types.
+ */
+/** The service name every `db` provider registers. */
+declare const DB_SERVICE = "db";
+/** The table that records an app's migration version. */
+declare const MIGRATIONS_TABLE = "_migrations";
+//#endregion
+export { Migration as a, DbExecutor as c, validateSchemaPrefix as i, SqlValue as l, MIGRATIONS_TABLE as n, applyMigrations as o, readMigrationFiles as r, Db as s, DB_SERVICE as t };

package/lib/kv/db.d.ts

@@ -1,5 +1,5 @@
-import { t as Db } from "../database-D_UN6We8.js";
-import { t as Kv } from "../kv-DWDm0Lja.js";
+import { s as Db } from "../index-D4FAsBZu.js";
+import { f as Kv } from "../index-BLTYsyc1.js";
 
 //#region ../../plugins/acryl-kv-db/src/open.d.ts
 interface KvOnDbOptions {

package/lib/kv/json.d.ts

@@ -1,4 +1,4 @@
-import { n as KvOpened, t as Kv } from "../kv-DWDm0Lja.js";
+import { f as Kv, p as KvOpened } from "../index-BLTYsyc1.js";
 
 //#region ../../plugins/acryl-kv-json/src/open.d.ts
 interface OpenKvOptions {