acrylblends 0.7.5 → 0.7.7

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": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+  },
+  "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')
+}

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

@@ -0,0 +1,80 @@
+/**
+ * The plain way to use SQL as the `kv` store, for code without Cordis (an acrylblends app): `kvOnDb(db)` gives the `kv` port over a `kv`
+ * table of the `db` port (SQLite today, Postgres after spec 049 slice 2), so an app that grows from a JSON file into SQL keeps its data. The
+ * Cordis plugin is a thin wrapper over it. This entry imports nothing from Cordis.
+ *
+ * The table is created on first use with `CREATE TABLE IF NOT EXISTS`, so it needs no migration of the app's. `update` reads and writes in
+ * one `db.transaction`. `list` selects with `substr(key, 1, n) = ?`, not `LIKE`, so `%`, `_` and letter case need no escaping, and sorts by
+ * code point in the end, whatever collation the database sorts with.
+ */
+
+import type { Db } from '../../acryl-db/src/index.ts'
+import { checkKey, codePoints, compareKeys, decodeValue, encodeValue, type Kv, runChange } from '../../acryl-kv/src/index.ts'
+
+export type { Kv } from '../../acryl-kv/src/index.ts'
+
+export interface KvOnDbOptions {
+  /** The table that holds the documents. Defaults to `kv`; a plain SQL identifier. */
+  readonly table?: string
+}
+
+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. */
+export function kvOnDb(db: Db, options: KvOnDbOptions = {}): Kv {
+  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: Promise<void> | undefined
+  const ensure = (): Promise<void> => {
+    ready ??= db.exec(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`).catch((error: unknown) => {
+      ready = undefined
+      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 <T>(work: () => Promise<T>): Promise<T> => {
+    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<T>(key: string) {
+      checkKey(key)
+      const row = await after(() => db.get<{ value: string }>(`SELECT value FROM ${table} WHERE key = ?`, key))
+      return row === undefined ? undefined : decodeValue<T>(row.value)
+    },
+    async set(key, value) {
+      checkKey(key)
+      const text = encodeValue(value)
+      await after(() => db.run(upsert, key, text))
+    },
+    async update<T>(key: string, change: (current: T | undefined) => T) {
+      checkKey(key)
+      return after(() => db.transaction(async tx => {
+        const row = await tx.get<{ value: string }>(`SELECT value FROM ${table} WHERE key = ?`, key)
+        const next = runChange(change, row === undefined ? undefined : decodeValue<T>(row.value))
+        const text = encodeValue(next)
+        await tx.run(upsert, key, text)
+        return decodeValue<T>(text)
+      }))
+    },
+    async delete(key) {
+      checkKey(key)
+      await after(() => db.run(`DELETE FROM ${table} WHERE key = ?`, key))
+    },
+    async list(prefix = '') {
+      const rows = await after(() => prefix === ''
+        ? db.all<{ key: string }>(`SELECT key FROM ${table}`)
+        : db.all<{ key: string }>(`SELECT key FROM ${table} WHERE substr(key, 1, ?) = ?`, codePoints(prefix), prefix))
+      return rows.map(row => row.key).sort(compareKeys)
+    },
+  }
+}

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

@@ -0,0 +1,21 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-kv-db",
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 10,
+  "digest": "sha256:266a44080a78b3d10fc05e5b83a39599e44a5be998eb97368aa07507ac4e3a48",
+  "testsNotRun": {
+    "tests/loader.spec.ts": "loads the plugin through the real Loader (@deepseek-ai/cordis-plugin-loader), which generated apps do not install; kvOnDb is tested here by open.spec.ts and conformance.spec.ts",
+    "tests/plain-entry-imports.spec.ts": "a copy vendored into an app (with relative imports, no build of its own) has neither `lib/`; the app's own typecheck is what proves the copy names no Cordis type it does not provide."
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

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

@@ -0,0 +1,13 @@
+{
+  "name": "acryl-kv-json",
+  "description": "The JSON-file provider of the kv port: one file in the app home, rewritten atomically (temp file, then rename) on every write. Vendored from ACRYL.",
+  "requires": ["acryl-kv", "instance"],
+  "inject": [],
+  "provides": ["kv"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "mount": "mount it after instance: root.plugin(kvJson, {}) (the file is kv.json in the app home, or set path); then a plugin that declares inject: ['kv'] calls await ctx.kv.set('theme', 'dark') and ctx.kv.update('visits', (n) => (n ?? 0) + 1)",
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+}

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

@@ -0,0 +1,71 @@
+/**
+ * The JSON-file provider of the `kv` port (spec 049 slice 3): one file, rewritten atomically on every write, opened with the plain
+ * `openKv` and provided as `kv` by this Cordis plugin. App plugins declare `inject: ['kv']` and import types from `acryl-kv` only, so
+ * replacing this row with `acryl-kv-db` does not touch them.
+ *
+ * Unloading withdraws `kv` first, so consumers stop calling, and then closes the store: the close waits for the writes in flight.
+ */
+
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { KV_SERVICE } from '../../acryl-kv/src/index.ts'
+import { openKv } from './open.ts'
+
+export { openKv, type OpenKvOptions } from './open.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-kv-json'
+
+/**
+ * What this plugin reads of the runtime's optional `appInstance` service: its home folder. The service belongs to the runtime (and to an
+ * app's own instance plugin), so this plugin declares no type for it on Cordis' Context; it checks the one field it uses at runtime.
+ */
+interface AppHome {
+  readonly home: string
+}
+
+function isAppHome(value: unknown): value is AppHome {
+  return typeof value === 'object' && value !== null && 'home' in value && typeof value.home === 'string'
+}
+
+export interface Config {
+  path?: string
+}
+
+export const Config: z<Config> = z.object({
+  path: z.string().description('The JSON file, absolute or relative to the app. Defaults to kv.json in the ACRYL app home; required where there is none.'),
+})
+
+/** The file name used in the app home when `path` is not configured. */
+export const DEFAULT_FILE = 'kv.json'
+
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+function resolveFromApp(ctx: Context, path: string): string {
+  if (path.startsWith('file:')) return fileURLToPath(path)
+  if (isAbsolute(path)) return path
+  const base = ctx.baseUrl
+  if (base === undefined || !base.startsWith('file:')) {
+    throw new Error(`acryl-kv-json: path ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`)
+  }
+  const appDir = base.endsWith('/') ? fileURLToPath(base) : dirname(fileURLToPath(base))
+  return resolve(appDir, path)
+}
+
+export async function apply(ctx: Context, rawConfig: Config = {}): Promise<void> {
+  const config = Config(rawConfig)
+  // The app home comes from the runtime's `appInstance` service when this runs inside an ACRYL app; a plain framework app names its file.
+  const appInstance: unknown = ctx.get('appInstance')
+  let file: string
+  if (config.path !== undefined) file = resolveFromApp(ctx, config.path)
+  else if (isAppHome(appInstance)) file = join(appInstance.home, DEFAULT_FILE)
+  else throw new Error('acryl-kv-json: no file path; set `path` in this row\'s config (there is no ACRYL app home to default to)')
+
+  // Disposers run in reverse: the service is withdrawn before the store closes.
+  await ctx.effect(async function* () {
+    const opened = await openKv({ path: file })
+    yield () => opened.close()
+    yield ctx.reflect.provide(KV_SERVICE, opened.kv)
+  }, `acryl-kv-json: ${file}`)
+}

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

@@ -0,0 +1,185 @@
+/**
+ * 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.
+ */
+
+import { mkdir, open, readdir, readFile, rename, rm } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+import { checkKey, compareKeys, decodeValue, encodeValue, type Kv, type KvOpened, runChange } from '../../acryl-kv/src/index.ts'
+
+export type { Kv, KvOpened } from '../../acryl-kv/src/index.ts'
+
+export interface OpenKvOptions {
+  /** The JSON file; its folder is created if missing. */
+  readonly path: string
+}
+
+/** 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: string): string => `${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: ReadonlyMap<string, string>): string {
+  const body = [...entries.keys()].sort(compareKeys).map(key => `${JSON.stringify(key)}:${entries.get(key)}`).join(',')
+  return `{"version":${FORMAT},"entries":{${body}}}\n`
+}
+
+function unreadable(file: string, reason: string): Error {
+  return 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: string): Promise<Map<string, string>> {
+  let text: string
+  try {
+    text = await readFile(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return new Map()
+    throw error
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw unreadable(file, (error as Error).message)
+  }
+  if (typeof parsed !== 'object' || parsed === null || (parsed as { version?: unknown }).version !== FORMAT) throw unreadable(file, 'not a version 1 kv file')
+  const entries = (parsed as { entries?: unknown }).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: string): Promise<void> {
+  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: string, to: string): Promise<void> {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await rename(from, to)
+      return
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).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: string): Promise<void> {
+  if (process.platform === 'win32') return
+  try {
+    const handle = await open(folder, 'r')
+    try {
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+  } catch {
+    // Best effort: the rename itself is already atomic.
+  }
+}
+
+/** Open (and create, when missing) a JSON-file store. @throws when the file exists and is not a readable kv file. */
+export async function openKv(options: OpenKvOptions): Promise<KvOpened> {
+  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<unknown> = Promise.resolve()
+
+  const guard = (): void => {
+    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: ReadonlyMap<string, string>): Promise<void> => {
+    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 = <T>(change: (draft: Map<string, string>) => T): Promise<T> => {
+    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(() => undefined)
+    return task
+  }
+
+  const kv: Kv = {
+    async get<T>(key: string) {
+      guard()
+      checkKey(key)
+      const text = state.get(key)
+      return text === undefined ? undefined : decodeValue<T>(text)
+    },
+    async set(key, value) {
+      checkKey(key)
+      const text = encodeValue(value)
+      await write(draft => { draft.set(key, text) })
+    },
+    async update<T>(key: string, change: (current: T | undefined) => T) {
+      checkKey(key)
+      return write(draft => {
+        const text = draft.get(key)
+        const next = runChange(change, text === undefined ? undefined : decodeValue<T>(text))
+        const encoded = encodeValue(next)
+        draft.set(key, encoded)
+        return decodeValue<T>(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)
+    },
+  }
+
+  return {
+    kv,
+    close: async () => {
+      closed = true
+      await tail
+    },
+  }
+}