acrylblends 0.7.5 → 0.7.7

package/lib/kv/db.js

@@ -0,0 +1,57 @@
+import { a as compareKeys, c as runChange, i as codePoints, o as decodeValue, r as checkKey, s as encodeValue } from "../src-DRFVEQQb.js";
+//#region ../../plugins/acryl-kv-db/src/open.ts
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/u;
+/** The `kv` port over a `db`. It does not own the database: whoever opened it closes it, and calls after that reject. */
+function kvOnDb(db, options = {}) {
+	const table = options.table ?? "kv";
+	if (!IDENTIFIER.test(table)) throw new TypeError(`acryl-kv-db: the table name must be a plain lower case SQL identifier, got ${JSON.stringify(table)}`);
+	let ready;
+	const ensure = () => {
+		ready ??= db.exec(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`).catch((error) => {
+			ready = void 0;
+			throw error;
+		});
+		return ready;
+	};
+	/**
+	* Run a statement after the table exists. The table's statement and this one are both handed to the database at once (its queue keeps
+	* their order), so a `close()` called right after a write cannot slip between them and leave the write on a closed database.
+	*/
+	const after = async (work) => {
+		const created = ensure();
+		const result = work();
+		const [, value] = await Promise.all([created, result]);
+		return value;
+	};
+	const upsert = `INSERT INTO ${table} (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`;
+	return {
+		async get(key) {
+			checkKey(key);
+			const row = await after(() => db.get(`SELECT value FROM ${table} WHERE key = ?`, key));
+			return row === void 0 ? void 0 : decodeValue(row.value);
+		},
+		async set(key, value) {
+			checkKey(key);
+			const text = encodeValue(value);
+			await after(() => db.run(upsert, key, text));
+		},
+		async update(key, change) {
+			checkKey(key);
+			return after(() => db.transaction(async (tx) => {
+				const row = await tx.get(`SELECT value FROM ${table} WHERE key = ?`, key);
+				const text = encodeValue(runChange(change, row === void 0 ? void 0 : decodeValue(row.value)));
+				await tx.run(upsert, key, text);
+				return decodeValue(text);
+			}));
+		},
+		async delete(key) {
+			checkKey(key);
+			await after(() => db.run(`DELETE FROM ${table} WHERE key = ?`, key));
+		},
+		async list(prefix = "") {
+			return (await after(() => prefix === "" ? db.all(`SELECT key FROM ${table}`) : db.all(`SELECT key FROM ${table} WHERE substr(key, 1, ?) = ?`, codePoints(prefix), prefix))).map((row) => row.key).sort(compareKeys);
+		}
+	};
+}
+//#endregion
+export { kvOnDb };

package/lib/kv/json.d.ts

@@ -0,0 +1,11 @@
+import { n as KvOpened, t as Kv } from "../kv-DWDm0Lja.js";
+
+//#region ../../plugins/acryl-kv-json/src/open.d.ts
+interface OpenKvOptions {
+  /** The JSON file; its folder is created if missing. */
+  readonly path: string;
+}
+/** Open (and create, when missing) a JSON-file store. @throws when the file exists and is not a readable kv file. */
+declare function openKv(options: OpenKvOptions): Promise<KvOpened>;
+//#endregion
+export { type Kv, type KvOpened, OpenKvOptions, openKv };

package/lib/kv/json.js

@@ -0,0 +1,161 @@
+import { a as compareKeys, c as runChange, o as decodeValue, r as checkKey, s as encodeValue } from "../src-DRFVEQQb.js";
+import { mkdir, open, readFile, readdir, rename, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+//#region ../../plugins/acryl-kv-json/src/open.ts
+/**
+* The plain way to open the JSON-file provider, for code without Cordis (an acrylblends app): `openKv({ path })` reads one JSON file into
+* memory and resolves the `kv` 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.
+*
+* Every write queues behind the writes before it and persists the whole map: serialize to a temporary file in the same folder, flush it,
+* rename it over the file, and flush the folder where the platform allows. The call resolves after the rename, so a crash leaves the old file
+* or the new one, never half of one. One process owns the file: two writers would overwrite each other.
+*/
+/** The file's own format version, for a later change of layout. */
+const FORMAT = 1;
+/** Stray temporary files from a crash end in `.tmp` and start with the file's name. */
+const tempPrefix = (file) => `${basename(file)}.`;
+/** The file content for a map of key to JSON text, keys in code point order, so the same data is the same bytes. */
+function serialize(entries) {
+	const body = [...entries.keys()].sort(compareKeys).map((key) => `${JSON.stringify(key)}:${entries.get(key)}`).join(",");
+	return `{"version":${FORMAT},"entries":{${body}}}\n`;
+}
+function unreadable(file, reason) {
+	return /* @__PURE__ */ new Error(`acryl-kv-json: ${file} is not a readable kv file (${reason}); it was not changed`);
+}
+/** The entries of a file, or none when it does not exist. A file that exists and does not parse is an error: it is never started over. */
+async function load(file) {
+	let text;
+	try {
+		text = await readFile(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return /* @__PURE__ */ new Map();
+		throw error;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw unreadable(file, error.message);
+	}
+	if (typeof parsed !== "object" || parsed === null || parsed.version !== FORMAT) throw unreadable(file, "not a version 1 kv file");
+	const entries = parsed.entries;
+	if (typeof entries !== "object" || entries === null || Array.isArray(entries)) throw unreadable(file, "no entries object");
+	return new Map(Object.entries(entries).map(([key, value]) => [key, JSON.stringify(value)]));
+}
+/** Remove the temporary files an earlier crash left beside the file. */
+async function removeStrays(file) {
+	const prefix = tempPrefix(file);
+	for (const name of await readdir(dirname(file))) if (name.startsWith(prefix) && name.endsWith(".tmp")) await rm(join(dirname(file), name), { force: true });
+}
+const RENAME_RETRIES = 8;
+/** Rename over the target. Windows refuses while a scanner or an indexer holds the target for a moment, so it is retried briefly. */
+async function replace(from, to) {
+	for (let attempt = 0;; attempt += 1) try {
+		await rename(from, to);
+		return;
+	} catch (error) {
+		const code = error.code;
+		if (attempt >= RENAME_RETRIES || code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") throw error;
+		await new Promise((resolveWait) => setTimeout(resolveWait, 10 * (attempt + 1)));
+	}
+}
+/** Flush the folder entry of a renamed file (POSIX); Windows cannot open a folder, and a filesystem that refuses is no worse than before. */
+async function flushFolder(folder) {
+	if (process.platform === "win32") return;
+	try {
+		const handle = await open(folder, "r");
+		try {
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	} catch {}
+}
+/** Open (and create, when missing) a JSON-file store. @throws when the file exists and is not a readable kv file. */
+async function openKv(options) {
+	const file = resolve(options.path);
+	await mkdir(dirname(file), { recursive: true });
+	await removeStrays(file);
+	let state = await load(file);
+	let closed = false;
+	let sequence = 0;
+	let tail = Promise.resolve();
+	const guard = () => {
+		if (closed) throw new Error(`acryl-kv-json: ${file} is closed`);
+	};
+	/** Persist a map: the file is the old one or this one, never between. */
+	const persist = async (next) => {
+		sequence += 1;
+		const temp = join(dirname(file), `${tempPrefix(file)}${process.pid}.${sequence}.tmp`);
+		try {
+			const handle = await open(temp, "w");
+			try {
+				await handle.writeFile(serialize(next), "utf8");
+				await handle.sync();
+			} finally {
+				await handle.close();
+			}
+			await replace(temp, file);
+		} catch (error) {
+			await rm(temp, { force: true });
+			throw error;
+		}
+		await flushFolder(dirname(file));
+	};
+	/** Run a change after every earlier one; the map it works on becomes the state only once it is on disk. */
+	const write = (change) => {
+		guard();
+		const task = tail.then(async () => {
+			const draft = new Map(state);
+			const result = change(draft);
+			await persist(draft);
+			state = draft;
+			return result;
+		});
+		tail = task.catch(() => void 0);
+		return task;
+	};
+	return {
+		kv: {
+			async get(key) {
+				guard();
+				checkKey(key);
+				const text = state.get(key);
+				return text === void 0 ? void 0 : decodeValue(text);
+			},
+			async set(key, value) {
+				checkKey(key);
+				const text = encodeValue(value);
+				await write((draft) => {
+					draft.set(key, text);
+				});
+			},
+			async update(key, change) {
+				checkKey(key);
+				return write((draft) => {
+					const text = draft.get(key);
+					const encoded = encodeValue(runChange(change, text === void 0 ? void 0 : decodeValue(text)));
+					draft.set(key, encoded);
+					return decodeValue(encoded);
+				});
+			},
+			async delete(key) {
+				checkKey(key);
+				await write((draft) => {
+					draft.delete(key);
+				});
+			},
+			async list(prefix = "") {
+				guard();
+				return [...state.keys()].filter((key) => key.startsWith(prefix)).sort(compareKeys);
+			}
+		},
+		close: async () => {
+			closed = true;
+			await tail;
+		}
+	};
+}
+//#endregion
+export { openKv };

package/lib/kv-DWDm0Lja.d.ts

@@ -0,0 +1,39 @@
+//#region ../../plugins/acryl-kv/lib/types/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
+export { KvOpened as n, Kv as t };

package/lib/kv.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 { type CopyKvOptions, type CopyKvResult, type JsonValue, KV_SERVICE, type Kv, type KvOpened, type NotPromise, checkKey, codePoints, compareKeys, copyKv, decodeValue, encodeValue, runChange };

package/lib/kv.js

@@ -0,0 +1,2 @@
+import { a as compareKeys, c as runChange, i as codePoints, n as copyKv, o as decodeValue, r as checkKey, s as encodeValue, t as KV_SERVICE } from "./src-DRFVEQQb.js";
+export { KV_SERVICE, checkKey, codePoints, compareKeys, copyKv, decodeValue, encodeValue, runChange };

package/lib/src-DRFVEQQb.js

@@ -0,0 +1,90 @@
+//#region ../../plugins/acryl-kv/src/check.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. */
+function checkKey(key) {
+	if (typeof key !== "string" || key === "") throw new TypeError(`a kv key is a non-empty string, got ${typeof key === "string" ? "an empty string" : typeof key}`);
+}
+/**
+* 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.
+*/
+function encodeValue(value) {
+	const text = JSON.stringify(value, (_key, part) => {
+		if (typeof part === "number" && !Number.isFinite(part)) throw new TypeError(`a kv value is JSON; ${String(part)} is not`);
+		return part;
+	});
+	if (text === void 0) throw new TypeError(`a kv value is JSON; ${typeof value} is not`);
+	return text;
+}
+/** The value of stored JSON text: a new copy each time, so changing what `get` returned changes nothing stored. */
+function decodeValue(text) {
+	return JSON.parse(text);
+}
+/** Order two keys by code point (the order of UTF-8 bytes, which SQLite's binary collation and Postgres' "C" collation give too). */
+function compareKeys(a, b) {
+	if (a === b) return 0;
+	const rank = (unit) => unit >= 55296 ? unit >= 57344 ? unit - 2048 : unit + 8192 : unit;
+	const length = Math.min(a.length, b.length);
+	for (let index = 0; index < length; index += 1) {
+		const difference = rank(a.charCodeAt(index)) - rank(b.charCodeAt(index));
+		if (difference !== 0) return difference;
+	}
+	return a.length - b.length;
+}
+/** The number of code points in a string (what SQL's `substr` counts). */
+function codePoints(text) {
+	let count = 0;
+	for (const _ of text) count += 1;
+	return count;
+}
+/**
+* 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 `{}`.
+*/
+function runChange(change, current) {
+	const next = change(current);
+	if (typeof next === "object" && next !== null && typeof next.then === "function") throw new TypeError("the callback of kv.update is synchronous and returned a promise: read what you need first (await kv.get), then update with a plain function");
+	return next;
+}
+//#endregion
+//#region ../../plugins/acryl-kv/src/copy.ts
+/**
+* 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.
+*/
+async function copyKv(source, target, options = {}) {
+	const keys = await source.list(options.prefix);
+	const existing = new Set(await target.list(options.prefix));
+	const shared = keys.filter((key) => existing.has(key));
+	if (shared.length > 0 && options.overwrite !== true) {
+		const shown = shared.slice(0, 5).map((key) => JSON.stringify(key)).join(", ");
+		throw new Error(`copyKv: the target already has ${shared.length} of these keys (${shown}${shared.length > 5 ? ", ..." : ""}); pass overwrite to replace them`);
+	}
+	let copied = 0;
+	for (const key of keys) {
+		const value = await source.get(key);
+		if (value === void 0) continue;
+		await target.set(key, value);
+		copied += 1;
+	}
+	return {
+		copied,
+		overwritten: shared.length
+	};
+}
+//#endregion
+//#region ../../plugins/acryl-kv/src/index.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. */
+const KV_SERVICE = "kv";
+//#endregion
+export { compareKeys as a, runChange as c, codePoints as i, copyKv as n, decodeValue as o, checkKey as r, encodeValue as s, KV_SERVICE as t };

package/package.json

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

package/plugins/acryl-db/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-db",
-    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",

package/plugins/acryl-db-sqlite/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-db-sqlite",
-    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",

package/plugins/acryl-kv/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-kv/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acryl-kv",
+  "description": "The kv port: named JSON documents for an app too small for SQL, with atomic update; types, checks and copyKv (the import). A provider (acryl-kv-json, acryl-kv-db) 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: ['kv'] and imports the ctx.kv type from './plugins/acryl-kv/src/cordis.ts'; add acryl-kv-json (a file) or acryl-kv-db (your SQL database) to provide it",
+  "omit": ["src/conformance.ts", "**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+}

package/plugins/acryl-kv/src/check.ts

@@ -0,0 +1,58 @@
+/**
+ * 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. */
+export function checkKey(key: unknown): asserts key is string {
+  if (typeof key !== 'string' || key === '') throw new TypeError(`a kv key is a non-empty string, got ${typeof key === 'string' ? 'an empty string' : typeof key}`)
+}
+
+/**
+ * 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.
+ */
+export function encodeValue(value: unknown): string {
+  const text = JSON.stringify(value, (_key, part: unknown) => {
+    if (typeof part === 'number' && !Number.isFinite(part)) throw new TypeError(`a kv value is JSON; ${String(part)} is not`)
+    return part
+  })
+  if (text === undefined) throw new TypeError(`a kv value is JSON; ${typeof value} is not`)
+  return text
+}
+
+/** The value of stored JSON text: a new copy each time, so changing what `get` returned changes nothing stored. */
+export function decodeValue<T>(text: string): T {
+  return JSON.parse(text) as T
+}
+
+/** Order two keys by code point (the order of UTF-8 bytes, which SQLite's binary collation and Postgres' "C" collation give too). */
+export function compareKeys(a: string, b: string): number {
+  if (a === b) return 0
+  // UTF-16 order puts astral characters (surrogates, D800-DFFF) before U+E000-U+FFFF; moving the surrogates above them gives code point order.
+  const rank = (unit: number): number => (unit >= 0xd800 ? (unit >= 0xe000 ? unit - 0x800 : unit + 0x2000) : unit)
+  const length = Math.min(a.length, b.length)
+  for (let index = 0; index < length; index += 1) {
+    const difference = rank(a.charCodeAt(index)) - rank(b.charCodeAt(index))
+    if (difference !== 0) return difference
+  }
+  return a.length - b.length
+}
+
+/** The number of code points in a string (what SQL's `substr` counts). */
+export function codePoints(text: string): number {
+  let count = 0
+  for (const _ of text) count += 1
+  return count
+}
+
+/**
+ * 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 `{}`.
+ */
+export function runChange<T>(change: (current: T | undefined) => T, current: T | undefined): T {
+  const next: unknown = change(current)
+  if (typeof next === 'object' && next !== null && typeof (next as { then?: unknown }).then === 'function') {
+    throw new TypeError('the callback of kv.update is synchronous and returned a promise: read what you need first (await kv.get), then update with a plain function')
+  }
+  return next as T
+}