acrylblends 0.7.4 → 0.7.5

package/docs/framework/guides/forms-and-sessions.md

@@ -3,31 +3,34 @@
 This page shows the parts a small multi-user app needs, in the order an app uses them: a database, passwords, a cookie session, HTML forms with server-side validation, and a JSON API that shares the same rules.
 It is the shape of a "Notes" app built from these docs alone (sign up, log in, create, edit, delete and search notes, a typed test client for the API).
 
-## A database with `node:sqlite`
-
-Node.js 22.19 and later include SQLite, so there is nothing to install. `DatabaseSync` is synchronous, which suits a small app.
+## A database with the `db` port
+
+`openDb` from `acrylblends/db/sqlite` opens a SQLite file (Node.js 22.19 and later include SQLite, so there is nothing to install), applies the SQL files in `migrations/`, and returns `{ db, close }`.
+Every call on `db` returns a promise, so `await` it. The [data guide](data.md) has the whole story: migrations, transactions, tests and shutdown.
+
+```sql
+-- migrations/001-notes.sql
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL
+);
+
+CREATE TABLE sessions (
+  token TEXT PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
+);
+```
 
 ```ts
-import { DatabaseSync } from 'node:sqlite'
-
-export function openDb(path = process.env.NOTES_DB ?? 'notes.db'): DatabaseSync {
-  const db = new DatabaseSync(path)
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS users (
-      id INTEGER PRIMARY KEY,
-      email TEXT NOT NULL UNIQUE,
-      password_hash TEXT NOT NULL
-    );
-    CREATE TABLE IF NOT EXISTS sessions (
-      token TEXT PRIMARY KEY,
-      user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
-    );
-  `)
-  return db
+import { openDb } from 'acrylblends/db/sqlite'
+
+export function openNotesDb(path = process.env.NOTES_DB ?? 'data/notes.sqlite') {
+  return openDb({ path, migrations: 'migrations' })
 }
 ```
 
-Take the database as an argument (`createApp(db)`) instead of opening it at import time. A test then passes `openDb(':memory:')`, and importing the app module does not create a file.
+Take the database as an argument (`createApp(db)`) instead of opening it at import time. A test then opens `openNotesDb(':memory:')`, and importing the app module does not create a file.
 
 ## Passwords with `node:crypto`
 
@@ -63,20 +66,21 @@ import { Acryl } from 'acrylblends'
 import { createMiddleware } from 'acrylblends/factory'
 import { deleteCookie, getCookie, setCookie } from 'acrylblends/cookie'
 import { randomBytes } from 'node:crypto'
-import type { DatabaseSync } from 'node:sqlite'
+import type { Db } from 'acrylblends/db'
 
 type Env = { Variables: { user: { id: number; email: string } } }
 
-export function createApp(db: DatabaseSync) {
+export function createApp(db: Db) {
   const userFor = (token: string | undefined) =>
     token
-      ? (db
-          .prepare('SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?')
-          .get(token) as { id: number; email: string } | undefined)
+      ? db.get<{ id: number; email: string }>(
+          'SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?',
+          token
+        )
       : undefined
 
   const requireUser = createMiddleware<Env>(async (c, next) => {
-    const user = userFor(getCookie(c, 'sid'))
+    const user = await userFor(getCookie(c, 'sid'))
     if (!user) return c.redirect('/login')
     c.set('user', user)
     await next()
@@ -87,16 +91,16 @@ export function createApp(db: DatabaseSync) {
   app.use('/notes/*', requireUser)
   app.get('/notes', (c) => c.text(`Hello ${c.get('user').email}`))
 
-  app.post('/login-example', (c) => {
+  app.post('/login-example', async (c) => {
     const token = randomBytes(32).toString('hex')
-    db.prepare('INSERT INTO sessions (token, user_id) VALUES (?, ?)').run(token, 1)
+    await db.run('INSERT INTO sessions (token, user_id) VALUES (?, ?)', token, 1)
     setCookie(c, 'sid', token, { path: '/', httpOnly: true, sameSite: 'Lax', maxAge: 60 * 60 * 24 * 30 })
     return c.redirect('/notes', 303)
   })
 
-  app.post('/logout', (c) => {
+  app.post('/logout', async (c) => {
     const token = getCookie(c, 'sid')
-    if (token) db.prepare('DELETE FROM sessions WHERE token = ?').run(token)
+    if (token) await db.run('DELETE FROM sessions WHERE token = ?', token)
     deleteCookie(c, 'sid', { path: '/' })
     return c.redirect('/login', 303)
   })

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
   },
-  "files": 98,
-  "digest": "sha256:396f882ac7b612455edc59961c52472fadc5f95ea1a778208e7edd860e4e6727"
+  "files": 99,
+  "digest": "sha256:ce484a4cf2bc9781d188fe468e98c498052d50155bb72f84c0a1ad384b1a5e85"
 }

package/lib/db/sqlite.d.ts

@@ -0,0 +1,27 @@
+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 {
+  /** The database file, its folder created if missing; `:memory:` for a database that lives until `close`. */
+  readonly path: string;
+  /** A folder of `NNN-name.sql` files numbered from 1, as a path or a file URL, applied in order before `openDb` resolves. */
+  readonly migrations?: string | URL;
+  /** How long SQLite waits for a competing file lock, in milliseconds. Defaults to 5000. */
+  readonly busyTimeoutMs?: number;
+  /** The WAL auto-checkpoint threshold in pages; 0 disables it. Defaults to 1000. */
+  readonly walAutoCheckpointPages?: number;
+}
+/** An open database: the port, and the one function that closes it. */
+interface OpenDb {
+  readonly db: Db;
+  /** Waits for running operations and transactions, checkpoints the WAL and releases the file. Calling it again does nothing. */
+  close(): Promise<void>;
+}
+/**
+ * Open, configure and migrate a SQLite database.
+ * @throws when the migration files are misnamed or misnumbered, or a migration fails (the file is closed, and unchanged), or the
+ *   database's schema is newer than the migrations.
+ */
+declare function openDb(options: OpenDbOptions): Promise<OpenDb>;
+//#endregion
+export { type Db, type DbExecutor, OpenDb, OpenDbOptions, type SqlValue, openDb };

package/lib/db/sqlite.js

@@ -0,0 +1,197 @@
+import { i as applyMigrations, n as MIGRATIONS_TABLE, r as readMigrationFiles } from "../src-MWcsMS8i.js";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+//#region ../../plugins/acryl-db-sqlite/src/facade/node.ts
+const DEFAULT_WAL_AUTO_CHECKPOINT_PAGES = 1e3;
+const DEFAULT_BUSY_TIMEOUT_MS = 5e3;
+const ignore = () => {};
+/**
+* Runs operations in call order. An operation starts immediately when nothing is running or waiting;
+* otherwise it waits for everything before it. An asynchronous operation holds the queue until it settles.
+*/
+var SerialOperationQueue = class {
+	tail = Promise.resolve();
+	pending = 0;
+	run(operation) {
+		if (this.pending > 0) return this.enqueue(operation);
+		try {
+			return Promise.resolve(operation());
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+	runAsync(operation) {
+		if (this.pending > 0) return this.enqueue(operation);
+		this.pending++;
+		const { promise: barrier, resolve: releaseBarrier } = Promise.withResolvers();
+		this.tail = barrier;
+		let started;
+		try {
+			started = operation();
+		} catch (error) {
+			started = Promise.reject(error);
+		}
+		return started.finally(() => {
+			this.pending--;
+			releaseBarrier();
+		});
+	}
+	enqueue(operation) {
+		this.pending++;
+		return this.release(this.tail.then(operation));
+	}
+	release(operation) {
+		const settled = operation.finally(() => {
+			this.pending--;
+		});
+		this.tail = settled.then(ignore, ignore);
+		return settled;
+	}
+};
+/**
+* Executes SQL on one connection. Prepared statements are cached per connection by SQL text, so the
+* database and its transaction handles share them across transactions.
+*/
+var NodeSqliteExecutor = class {
+	database;
+	statements;
+	constructor(database, statements) {
+		this.database = database;
+		this.statements = statements;
+	}
+	exec(sql) {
+		return this.runOperation(() => {
+			this.database.exec(sql);
+		});
+	}
+	run(sql, ...params) {
+		return this.runOperation(() => ({ changes: Number(this.statement(sql).run(...params).changes) }));
+	}
+	get(sql, ...params) {
+		return this.runOperation(() => this.statement(sql).get(...params));
+	}
+	all(sql, ...params) {
+		return this.runOperation(() => this.statement(sql).all(...params));
+	}
+	statement(sql) {
+		let statement = this.statements.get(sql);
+		if (statement === void 0) {
+			statement = this.database.prepare(sql);
+			this.statements.set(sql, statement);
+		}
+		return statement;
+	}
+};
+var NodeSqliteTransaction = class extends NodeSqliteExecutor {
+	scope;
+	constructor(database, statements, scope) {
+		super(database, statements);
+		this.scope = scope;
+	}
+	async runOperation(operation) {
+		if (!this.scope.active) throw new Error("SQLite transaction handle is no longer active");
+		return operation();
+	}
+};
+/** `Db` adapter backed by Node's built-in `node:sqlite`. */
+var NodeSqliteDatabase = class extends NodeSqliteExecutor {
+	access = new SerialOperationQueue();
+	closed = false;
+	constructor(database) {
+		super(database, /* @__PURE__ */ new Map());
+	}
+	transaction(callback) {
+		return this.access.runAsync(async () => {
+			this.database.exec("BEGIN IMMEDIATE");
+			const scope = { active: true };
+			try {
+				const result = await callback(new NodeSqliteTransaction(this.database, this.statements, scope));
+				scope.active = false;
+				this.database.exec("COMMIT");
+				return result;
+			} catch (error) {
+				scope.active = false;
+				try {
+					this.database.exec("ROLLBACK");
+				} catch (rollbackError) {
+					throw new AggregateError([error, rollbackError], "SQLite transaction failed and rollback failed");
+				}
+				throw error;
+			}
+		});
+	}
+	close() {
+		return this.access.run(() => {
+			if (this.closed) return;
+			this.closed = true;
+			this.statements.clear();
+			try {
+				this.database.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+			} finally {
+				this.database.close();
+			}
+		});
+	}
+	runOperation(operation) {
+		return this.access.run(operation);
+	}
+};
+/** Open and configure a Node-backed SQLite database facade. */
+async function openNodeSqliteDatabase(path, options = {}) {
+	const checkpointPages = options.walAutoCheckpointPages ?? DEFAULT_WAL_AUTO_CHECKPOINT_PAGES;
+	const timeout = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+	if (path !== ":memory:") await mkdir(dirname(path), { recursive: true });
+	const adapter = new NodeSqliteDatabase(new DatabaseSync(path, { timeout }));
+	try {
+		await adapter.exec("PRAGMA journal_mode = WAL");
+		await adapter.exec("PRAGMA synchronous = NORMAL");
+		await adapter.exec(`PRAGMA wal_autocheckpoint = ${checkpointPages}`);
+		return adapter;
+	} catch (error) {
+		try {
+			await adapter.close();
+		} catch {}
+		throw error;
+	}
+}
+//#endregion
+//#region ../../plugins/acryl-db-sqlite/src/open.ts
+/**
+* The plain way to open the SQLite provider, for code without Cordis (an acrylblends app): `openDb({ path, migrations })` opens one
+* `node:sqlite` file with the ported facade's settings (WAL, `synchronous = NORMAL`, a busy timeout) and foreign keys enforced, applies the
+* numbered migrations, and resolves the `db` port with the function that closes it. The Cordis plugin is a thin wrapper over this, so both
+* run one code path.
+* This entry imports nothing from Cordis.
+*/
+/**
+* Open, configure and migrate a SQLite database.
+* @throws when the migration files are misnamed or misnumbered, or a migration fails (the file is closed, and unchanged), or the
+*   database's schema is newer than the migrations.
+*/
+async function openDb(options) {
+	const migrations = options.migrations === void 0 ? [] : await readMigrationFiles(options.migrations);
+	const database = await openNodeSqliteDatabase(options.path, {
+		...options.busyTimeoutMs === void 0 ? {} : { busyTimeoutMs: options.busyTimeoutMs },
+		...options.walAutoCheckpointPages === void 0 ? {} : { walAutoCheckpointPages: options.walAutoCheckpointPages }
+	});
+	try {
+		await database.exec("PRAGMA foreign_keys = ON");
+		await applyMigrations(database, migrations, { table: MIGRATIONS_TABLE });
+	} catch (error) {
+		await database.close();
+		throw error;
+	}
+	return {
+		db: {
+			exec: (sql) => database.exec(sql),
+			run: (sql, ...params) => database.run(sql, ...params),
+			get: (sql, ...params) => database.get(sql, ...params),
+			all: (sql, ...params) => database.all(sql, ...params),
+			transaction: (work) => database.transaction(work)
+		},
+		close: () => database.close()
+	};
+}
+//#endregion
+export { openDb };

package/lib/db.d.ts

@@ -0,0 +1,2 @@
+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/db.js

@@ -0,0 +1,2 @@
+import { a as validateSchemaPrefix, i as applyMigrations, n as MIGRATIONS_TABLE, r as readMigrationFiles, t as DB_SERVICE } from "./src-MWcsMS8i.js";
+export { DB_SERVICE, MIGRATIONS_TABLE, applyMigrations, readMigrationFiles, validateSchemaPrefix };

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/src-MWcsMS8i.js

@@ -0,0 +1,85 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region ../../plugins/acryl-db/src/facade/schema.ts
+/** Validate a prefix before using it as part of a SQL identifier. */
+function validateSchemaPrefix(prefix) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) throw new Error(`Invalid SQL schema prefix ${JSON.stringify(prefix)}`);
+	if (prefix.toLowerCase().startsWith("sqlite_")) throw new Error(`SQL schema prefix ${JSON.stringify(prefix)} is reserved`);
+}
+//#endregion
+//#region ../../plugins/acryl-db/src/facade/migrations.ts
+/**
+* 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.
+*/
+async function applyMigrations(database, migrations, options) {
+	const { table } = options;
+	validateSchemaPrefix(table);
+	for (let index = 0; index < migrations.length; index++) if (migrations[index]?.version !== index + 1) throw new Error("Migrations must have contiguous versions starting at 1");
+	await database.transaction(async (transaction) => {
+		await transaction.exec(`CREATE TABLE IF NOT EXISTS ${table} (
+			singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+			version INTEGER NOT NULL CHECK (version >= 0)
+		)`);
+		await transaction.exec(`INSERT INTO ${table} (singleton, version) VALUES (1, 0) ON CONFLICT DO NOTHING`);
+		const row = await transaction.get(`SELECT version FROM ${table} WHERE singleton = 1`);
+		if (row === void 0) throw new Error("Schema metadata is missing");
+		const storedVersion = Number(row.version);
+		const currentVersion = migrations.at(-1)?.version ?? 0;
+		if (storedVersion > currentVersion) throw new Error(`Schema version ${storedVersion} is newer than supported version ${currentVersion}`);
+		for (const migration of migrations) {
+			if (migration.version <= storedVersion) continue;
+			for (const statement of migration.statements) await transaction.exec(statement);
+			await transaction.exec(`UPDATE ${table} SET version = ${String(migration.version)} WHERE singleton = 1`);
+		}
+	});
+}
+//#endregion
+//#region ../../plugins/acryl-db/src/migration-files.ts
+/**
+* An app's migrations as numbered SQL files: `migrations/001-notes.sql`, `002-tags.sql`, ... Each file is one migration, run as one
+* `exec` (so it may hold several statements), numbered from 1 with no gaps.
+*/
+const FILE = /^(\d+)-[a-z0-9][a-z0-9-]*\.sql$/u;
+/**
+* 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.
+*/
+async function readMigrationFiles(folder) {
+	const dir = typeof folder === "string" ? folder : fileURLToPath(folder);
+	const numbered = (await readdir(dir)).filter((name) => name.endsWith(".sql")).sort().map((name) => {
+		const match = FILE.exec(name);
+		if (match?.[1] === void 0) throw new Error(`acryl-db: migration file ${name} in ${dir} must be named NNN-name.sql, like 001-notes.sql`);
+		return {
+			name,
+			version: Number(match[1])
+		};
+	}).sort((a, b) => a.version - b.version);
+	numbered.forEach((file, index) => {
+		if (file.version !== index + 1) throw new Error(`acryl-db: migration ${file.name} in ${dir} should be number ${String(index + 1)}; the files must be numbered 1, 2, 3, ... with no gaps or repeats`);
+	});
+	return Promise.all(numbered.map(async (file) => ({
+		version: file.version,
+		statements: [await readFile(join(dir, file.name), "utf8")]
+	})));
+}
+//#endregion
+//#region ../../plugins/acryl-db/src/index.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. */
+const DB_SERVICE = "db";
+/** The table that records an app's migration version. */
+const MIGRATIONS_TABLE = "_migrations";
+//#endregion
+export { validateSchemaPrefix as a, applyMigrations as i, MIGRATIONS_TABLE as n, readMigrationFiles as r, DB_SERVICE as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -418,6 +418,14 @@
       "types": "./lib/node-server/register.d.ts",
       "default": "./lib/node-server/register.js"
     },
+    "./db": {
+      "types": "./lib/db.d.ts",
+      "default": "./lib/db.js"
+    },
+    "./db/sqlite": {
+      "types": "./lib/db/sqlite.d.ts",
+      "default": "./lib/db/sqlite.js"
+    },
     "./package.json": "./package.json",
     "./cli": {
       "types": "./dist/index.d.ts",

package/plugins/acryl-db/LICENSE

@@ -0,0 +1,47 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The files under src/facade are derived from the SQLite facade of chord in pi (https://github.com/earendil-works/pi, packages/chord, commit d5b3de22d0e24a3e9c38a9410d3329b099717283), used under this license:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/acryl-db/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acryl-db",
+  "description": "The db port: the relational database an app plugin sees through inject: ['db'], with numbered SQL migrations. Types and the migration runner; a provider (acryl-db-sqlite) serves it. Vendored from ACRYL.",
+  "requires": [],
+  "inject": [],
+  "provides": [],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "it is the port, not a service: a plugin declares inject: ['db'] and imports its types from './plugins/acryl-db/src/index.ts' (or the ctx.db type from './plugins/acryl-db/src/cordis.ts'); add acryl-db-sqlite to provide it",
+  "omit": ["src/conformance.ts", "**/*.test.*", "**/*.case.ts"]
+}

package/plugins/acryl-db/src/cordis.ts

@@ -0,0 +1,13 @@
+/**
+ * The `ctx.db` type for Cordis plugins: `import type {} from 'acryl-db/cordis'` beside `inject: ['db']`. Kept out of the root entry, so
+ * plain code that uses the port never names Cordis.
+ */
+
+import type {} from '@deepseek-ai/cordis'
+import type { Db } from './facade/database.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    db: Db
+  }
+}

package/plugins/acryl-db/src/facade/database.ts

@@ -0,0 +1,41 @@
+/** Values supported by the portable SQL drivers. */
+export 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.
+ */
+export 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`.
+ */
+export interface Db extends DbExecutor {
+	transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T>;
+}