acrylblends 0.7.6 → 0.7.8

package/lib/read-sse.d.ts

@@ -0,0 +1,33 @@
+//#region ../../plugins/acryl-router/src/helpers/read-sse.d.ts
+/**
+ * `readSSE(response)`: the events of a `text/event-stream` answer from `fetch`, for the browser. `EventSource` reads GET streams only; a chat
+ * or any stream that needs a POST body, a header or an `AbortSignal` is read with `fetch`, and this is the loop every such page otherwise writes by
+ * hand. It follows the parsing rules of the HTML standard (lines end in LF, CRLF or CR; the `data` lines of one event join with LF; a line that
+ * starts with a colon is a comment; an event ends at a blank line; an event with no `data` line is not dispatched; the last event is dispatched
+ * only if its blank line arrived), and it is one module with no imports, so it also runs in a service worker and on a fetch runtime.
+ *
+ * ACRYL's own addition, not part of the upstream port.
+ */
+/** One event of the stream. */
+interface SSEEvent {
+  /** The `event:` name; `message` when the event has none. */
+  readonly event: string;
+  /** The `data:` lines of the event, joined with a line feed. */
+  readonly data: string;
+  /** The `id:` of the event, when it had one. */
+  readonly id?: string;
+  /** The `retry:` of the event in milliseconds, when it had one. */
+  readonly retry?: number;
+}
+interface ReadSSEOptions {
+  /** Stops the loop and cancels the response body when it aborts. (Abort the `fetch` itself with the signal you pass to it.) */
+  readonly signal?: AbortSignal;
+}
+/**
+ * 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.
+ */
+declare function readSSE(response: Response, options?: ReadSSEOptions): AsyncGenerator<SSEEvent, void, undefined>;
+//#endregion
+export { ReadSSEOptions, SSEEvent, readSSE };

package/lib/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/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.6",
+  "version": "0.7.8",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -402,6 +402,10 @@
       "types": "./lib/schema-validator.d.ts",
       "default": "./lib/schema-validator.js"
     },
+    "./read-sse": {
+      "types": "./lib/read-sse.d.ts",
+      "default": "./lib/read-sse.js"
+    },
     "./node-server": {
       "types": "./lib/node-server.d.ts",
       "default": "./lib/node-server.js"
@@ -426,6 +430,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/plugin.json

@@ -7,6 +7,6 @@
   "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",
+  "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/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-db",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 0,
-  "digest": "sha256:51e5613457498bfab7c281e0c6443c4f7535401c16520ac44624dc8791a90fa6",
+  "digest": "sha256:656f5bb8468ea1d1f5cef2fc14c4c3d3c8cfa1d85a75cebbf6bc98f1b2d245a7",
   "testsNotRun": {},
   "notice": [
     "LICENSE"

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

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-db-sqlite",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "vendored": [
     "src",

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "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
+}

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

@@ -0,0 +1,39 @@
+import type { Kv } from './kv.ts'
+
+export 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
+}
+
+export 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.
+ */
+export async function copyKv(source: Kv, target: Kv, options: CopyKvOptions = {}): Promise<CopyKvResult> {
+  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)
+    // A key deleted from the source while copying is not copied.
+    if (value === undefined) continue
+    await target.set(key, value)
+    copied += 1
+  }
+  return { copied, overwritten: shared.length }
+}

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * 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. */
+export const KV_SERVICE = 'kv'
+
+export type { JsonValue, Kv, KvOpened, NotPromise } from './kv.ts'
+export { checkKey, codePoints, compareKeys, decodeValue, encodeValue, runChange } from './check.ts'
+export { copyKv, type CopyKvOptions, type CopyKvResult } from './copy.ts'

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

@@ -0,0 +1,37 @@
+/** `T`, except a promise: the callback of `update` is synchronous, and an async one is a type error. */
+export type NotPromise<T> = T extends PromiseLike<unknown> ? never : T
+
+/** Anything JSON can hold. */
+export 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.
+ */
+export 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. */
+export 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>
+}

package/plugins/acryl-kv/upstream.json

@@ -0,0 +1,18 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-kv",
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 0,
+  "digest": "sha256:dbf0d156d0f3d3b394e48cba87b015362f2720c96a3b198ae97ac5bea61c4ae4",
+  "testsNotRun": {},
+  "notice": [
+    "LICENSE"
+  ]
+}

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

@@ -0,0 +1,13 @@
+{
+  "name": "acryl-kv-db",
+  "description": "The kv provider over the db port: a kv table in the app's SQL database, so an app that grows into SQL keeps its data. Vendored from ACRYL.",
+  "requires": ["acryl-kv", "acryl-db-sqlite"],
+  "inject": ["db"],
+  "provides": ["kv"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "mount": "mount it after acryl-db-sqlite: root.plugin(kvDb, {}); it waits for db and provides the same kv as acryl-kv-json",
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+}

package/plugins/acryl-kv-db/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * The kv provider over the `db` port (spec 049 slice 3): a `kv` table in the app's SQL database, provided as `kv` by this Cordis plugin.
+ * It injects `db` and nothing else, so it stays PENDING until a `db` provider (`acryl-db-sqlite`, later Postgres) is active, and its
+ * consumers (`inject: ['kv']`) wait behind it. Replacing the row with `acryl-kv-json` does not touch them.
+ *
+ * It owns no connection, so unloading only withdraws `kv`.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { KV_SERVICE } from '../../acryl-kv/src/index.ts'
+import { kvOnDb } from './open.ts'
+
+export { kvOnDb, type KvOnDbOptions } from './open.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-kv-db'
+
+/** The service this plugin needs: Cordis starts it only while a `db` provider is active. */
+export const inject = ['db']
+
+export interface Config {
+  table?: string
+}
+
+export const Config: z<Config> = z.object({
+  table: z.string().description('The table that holds the documents. Defaults to kv.'),
+})
+
+export async function apply(ctx: Context, rawConfig: Config = {}): Promise<void> {
+  const config = Config(rawConfig)
+  const db = ctx.get('db') as Parameters<typeof kvOnDb>[0]
+  const kv = kvOnDb(db, config.table === undefined ? {} : { table: config.table })
+  await ctx.effect(async function* () {
+    yield ctx.reflect.provide(KV_SERVICE, kv)
+  }, 'acryl-kv-db')
+}