@deepseek-ai/dsh-storage-sqlite 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/storage/storage-sqlite/README.md
+README.md: 48aae14aa8613886d69652c39194878c190259cf
+README.zh.md: d95da614deb2fe4b6380532aa43836441a0db01c

package/README.md

@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-storage-sqlite
+
+English | [中文](README.zh.md)
+
+SQLite backend for the [storage hub](../storage/README.md): registers as backend `sqlite`, serving the `kv` facet over one `node:sqlite` database file (or `:memory:`). Design and trade-offs: [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md).
+
+## Storage model
+
+Document-per-row: each unit table becomes a physical `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)` STRICT table whose `value` is the record's JSON text, so one key updates one row (the reason to route a high-churn domain here instead of the JSON backend). Unit identity lives in two metadata tables — `units` stamps each unit's format version at first open and rejects a differing descriptor with `version-mismatch`; `unit_globals` holds each unit's global singleton row. The physical layout version lives in `PRAGMA user_version`; any other stamped value rejects (unreleased format, no migrations). Unit and table names are validated against the hub's `UNIT_NAME_RE` before they reach DDL, so no external input is ever interpolated into SQL identifiers.
+
+Every write primitive is a single prepared statement — SQLite's per-statement atomicity satisfies the KV contract without explicit transactions, and write ordering stays the caller's responsibility (the domain layer's write chain). Missing directories and database files are created owner-only (`0o700`/`0o600`), matching the session-persistence SQLite backend.
+
+## Configuration (schemastery)
+
+```ts
+interface Config {
+  path: string   // SQLite database file path, or ':memory:' for an in-process DB
+  journalMode?: 'wal' | 'delete' | 'truncate' | 'persist'   // journal_mode pragma; default 'wal'
+}
+```
+
+## Model Experience
+
+### Stored domain records
+
+#### What the model sees
+
+Nothing. This backend contributes no prompt, tool, or schema; it persists non-session domain data (workspace records, future session sidecar metadata) behind `ctx.storage` for host-side consumers only.
+
+#### Token effect
+
+Zero live-request tokens.
+
+#### KV Cache effect
+
+None — the backend never touches live request prefixes.
+
+## Known Limitations and Deferred Work
+
+- **`DatabaseSync` is synchronous** — each write blocks the event loop for its (single-statement) duration; acceptable at domain-data scale.
+- **No busy-wait or retry policy** — another connection holding a write transaction rejects the operation immediately; there is no multi-process write protection.
+- **Only the current `STORAGE_SQLITE_SCHEMA_VERSION` opens** — any other stamped version is rejected rather than migrated (pre-release stance).
+- **`openDatabase` duplicates the session-persistence SQLite open sequence** — extraction into a shared media layer is deferred to the planned session-backend migration (see the Agent Note's reuse audit).

package/README.zh.md

@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-storage-sqlite
+
+[English](README.md) | 中文
+
+[存储中心](../storage/README.md)的 SQLite 后端：注册为后端 `sqlite`，通过一个数据库文件提供 `kv` facet；该文件使用 `node:sqlite`（也可以是 `:memory:`）。设计与取舍见[领域 KV 存储 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)。
+
+## 存储模型
+
+每行一个文档：每个单元表都会成为一个物理 STRICT 表 `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)`，其中 `value` 是记录的 JSON 文本，因此一个 key 只更新一行（高频变更领域路由到这里而非 JSON 后端的原因）。单元标识位于两个元数据表中：`units` 在单元首次打开时标记其格式版本，描述符不同时以 `version-mismatch` 拒绝；`unit_globals` 保存每个单元的全局单例行。物理布局版本位于 `PRAGMA user_version`；其他任何标记值都会被拒绝（未发布格式，不迁移）。单元名和表名在进入 DDL 之前依据中心的 `UNIT_NAME_RE` 进行验证，因此不会把外部输入插值到 SQL 标识符中。
+
+每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 约定，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致。
+
+## 配置（schemastery）
+
+```ts
+interface Config {
+  path: string   // SQLite database file path, or ':memory:' for an in-process DB
+  journalMode?: 'wal' | 'delete' | 'truncate' | 'persist'   // journal_mode pragma; default 'wal'
+}
+```
+
+## 模型体验
+
+### 已存领域记录
+
+#### 模型看到的内容
+
+无。该后端不贡献提示词、工具或 schema；它在 `ctx.storage` 后面持久化非会话领域数据（工作区记录、未来的会话伴随元数据），只供主机侧消费方使用。
+
+#### Token 影响
+
+实时请求 token 为零。
+
+#### KV Cache 影响
+
+无：该后端从不触碰实时请求前缀。
+
+## 已知限制与暂缓事项
+
+- **`DatabaseSync` 是同步的**：每次写入都会在单条语句执行期间阻塞事件循环；在领域数据规模下可以接受。
+- **没有忙等待或重试策略**：另一个连接持有写事务时，该操作会立即被拒绝；没有多进程写入保护。
+- **只打开当前的 `STORAGE_SQLITE_SCHEMA_VERSION`**：其他任何已标记版本都会被拒绝而不是迁移（预发布立场）。
+- **`openDatabase` 重复了 session-persistence SQLite 打开顺序**：提取到共享介质层的工作暂缓至计划的会话后端迁移（见 Agent Note 的复用审计）。

package/lib/index.js

@@ -0,0 +1,308 @@
+import z from "@deepseek-ai/schemastery";
+import { StorageError, UNIT_NAME_RE, storageBackendServiceKey } from "@deepseek-ai/dsh-storage";
+import { DatabaseSync } from "node:sqlite";
+import { mkdir, open } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+//#region lib/types/schema.js
+/**
+* Schema + open-time helpers for the SQLite storage backend: the physical
+* layout version, the database open/configure sequence (permissions, pragmas,
+* version stamp/reject), and the unit metadata tables. Unit record tables are
+* created per descriptor in `unit.ts`.
+* @module @deepseek-ai/dsh-storage-sqlite/schema
+*/
+/**
+* The on-disk physical layout version, stored in `PRAGMA user_version`.
+* Orthogonal to each unit's own `version` (stamped per unit in the `units`
+* row). Bumped only on a breaking change to the table layout; any other
+* stamped version rejects — this unreleased format has no migrations.
+*/
+const STORAGE_SQLITE_SCHEMA_VERSION = 1;
+/**
+* Exclusively create a missing database file with owner-only permissions.
+* Existing files retain their modes, and errors other than `EEXIST` propagate.
+* `DatabaseSync` reopens by path, so this does not protect confidentiality or
+* integrity when another principal can replace the database entry in its
+* parent directory.
+*/
+async function createDatabaseFile(path) {
+	try {
+		await (await open(path, "wx", 384)).close();
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+	}
+}
+/**
+* Open the database and apply its schema and pragmas. Missing directories and
+* database files are created owner-only (`:memory:` skips filesystem setup).
+* A zero `user_version` is stamped with {@link STORAGE_SQLITE_SCHEMA_VERSION};
+* every other non-current version rejects rather than being migrated in place.
+* @param path - the SQLite database file to open, or `:memory:`.
+* @param journalMode - validated journal pragma.
+* @returns the open handle with pragmas applied and the unit metadata tables ensured.
+*/
+async function openDatabase(path, journalMode) {
+	const actual = path === ":memory:" ? path : resolve(path);
+	if (actual !== ":memory:") {
+		await mkdir(dirname(actual), {
+			recursive: true,
+			mode: 448
+		});
+		await createDatabaseFile(actual);
+	}
+	const db = new DatabaseSync(actual);
+	try {
+		configureDatabase(db, actual, journalMode);
+		return db;
+	} catch (error) {
+		db.close();
+		throw error;
+	}
+}
+function configureDatabase(db, path, journalMode) {
+	db.exec("PRAGMA foreign_keys = ON");
+	db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`);
+	const { user_version: onDisk } = db.prepare("PRAGMA user_version").get();
+	if (onDisk !== 0 && onDisk !== 1) throw new StorageError("version-mismatch", `storage database at "${path}" has schema version ${onDisk}, incompatible with this build (1)`);
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS units (
+      name    TEXT PRIMARY KEY,
+      version INTEGER NOT NULL
+    ) STRICT
+  `);
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS unit_globals (
+      unit  TEXT PRIMARY KEY REFERENCES units(name),
+      value TEXT NOT NULL
+    ) STRICT
+  `);
+	if (onDisk === 0) db.exec(`PRAGMA user_version = 1`);
+}
+/**
+* Physical table name for one unit table. Both segments are validated against
+* `UNIT_NAME_RE` before reaching this, so the result is safe to interpolate
+* into DDL and prepared-statement text.
+* @param unit - Validated unit name.
+* @param table - Validated table name.
+* @returns the `u_<unit>_<table>` identifier.
+*/
+function recordTableName(unit, table) {
+	return `u_${unit}_${table}`;
+}
+//#endregion
+//#region lib/types/unit.js
+/**
+* One opened SQLite KV unit: prepared per-table statements over the
+* `u_<unit>_<table>` record tables plus this unit's row in the shared
+* `unit_globals` table. Each primitive is a single statement, so atomicity
+* comes from SQLite itself — no explicit transactions, and no write queue
+* (write ordering is the caller's responsibility per the KV contract).
+* @module @deepseek-ai/dsh-storage-sqlite/unit
+*/
+/**
+* The SQLite {@link KvUnit}. Constructed by the backend AFTER the unit's
+* record tables exist; statements are prepared once here and reused for every
+* primitive. Values are stored as JSON text in the `value` column.
+*/
+var SqliteKvUnit = class {
+	descriptor;
+	onClose;
+	tables = /* @__PURE__ */ new Map();
+	globalUpsert;
+	globalSelect;
+	closed = false;
+	/**
+	* @param db - Open database handle owned by the backend (never closed here).
+	* @param descriptor - Validated descriptor whose record tables already exist.
+	* @param onClose - Backend callback releasing this unit's open-name slot.
+	*/
+	constructor(db, descriptor, onClose) {
+		this.descriptor = descriptor;
+		this.onClose = onClose;
+		for (const table of descriptor.tables) {
+			const physical = recordTableName(descriptor.name, table);
+			this.tables.set(table, {
+				upsert: db.prepare(`INSERT INTO "${physical}" (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`),
+				remove: db.prepare(`DELETE FROM "${physical}" WHERE key = ?`),
+				selectAll: db.prepare(`SELECT key, value FROM "${physical}"`)
+			});
+		}
+		this.globalUpsert = descriptor.hasGlobal ? db.prepare("INSERT INTO unit_globals (unit, value) VALUES (?, ?) ON CONFLICT(unit) DO UPDATE SET value = excluded.value") : void 0;
+		this.globalSelect = descriptor.hasGlobal ? db.prepare("SELECT value FROM unit_globals WHERE unit = ?") : void 0;
+	}
+	loadAll() {
+		return this.settle(() => {
+			const tables = {};
+			for (const [name, statements] of this.tables) {
+				const records = Object.create(null);
+				for (const row of statements.selectAll.all()) records[row.key] = this.parseValue(row.value, `table '${name}' key '${row.key}'`);
+				tables[name] = records;
+			}
+			let global = null;
+			if (this.globalSelect !== void 0) {
+				const row = this.globalSelect.get(this.descriptor.name);
+				if (row !== void 0) global = this.parseValue(row.value, "global slot");
+			}
+			return {
+				tables,
+				global
+			};
+		});
+	}
+	/** Parse one stored value column, mapping bad JSON to `malformed-medium`. */
+	parseValue(text, slot) {
+		try {
+			return JSON.parse(text);
+		} catch (error) {
+			throw new StorageError("malformed-medium", `kv unit '${this.descriptor.name}' holds unparsable JSON at ${slot}`, { cause: error });
+		}
+	}
+	putRecord(table, key, value) {
+		return this.settle(() => {
+			this.statementsFor(table).upsert.run(key, JSON.stringify(value));
+		});
+	}
+	deleteRecord(table, key) {
+		return this.settle(() => {
+			this.statementsFor(table).remove.run(key);
+		});
+	}
+	setGlobal(value) {
+		return this.settle(() => {
+			if (this.globalUpsert === void 0) throw new Error(`kv unit '${this.descriptor.name}' declared no global slot`);
+			this.globalUpsert.run(this.descriptor.name, JSON.stringify(value));
+		});
+	}
+	close() {
+		if (!this.closed) {
+			this.closed = true;
+			this.onClose();
+		}
+		return Promise.resolve();
+	}
+	/**
+	* Run one synchronous primitive behind the closed guard, mapping a throw to
+	* a rejection so the Promise-returning contract never throws synchronously.
+	*/
+	settle(operation) {
+		try {
+			this.ensureOpen();
+			return Promise.resolve(operation());
+		} catch (error) {
+			return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	ensureOpen() {
+		if (this.closed) throw new StorageError("closed", `kv unit '${this.descriptor.name}' is closed`);
+	}
+	statementsFor(table) {
+		const statements = this.tables.get(table);
+		if (statements === void 0) throw new Error(`kv unit '${this.descriptor.name}' declared no table '${table}'`);
+		return statements;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* SQLite storage backend for the storage hub: one database file hosts every
+* routed unit, document-per-row (`key TEXT` / `value TEXT` JSON). Registers
+* as backend `sqlite`; the disposer unregisters first, then closes the medium.
+* @module @deepseek-ai/dsh-storage-sqlite
+*/
+/** Cordis plugin name. */
+const name = "storage-sqlite";
+/** The backend registers on the storage hub. */
+const inject = ["storage"];
+/** Schemastery validator for {@link Config}. */
+const Config = z.object({
+	path: z.string().required(),
+	journalMode: z.union([
+		"wal",
+		"delete",
+		"truncate",
+		"persist"
+	]).default("wal")
+});
+/**
+* The SQLite {@link StorageBackend}. Owns one `DatabaseSync` connection and
+* the open-unit table; `kv.open` validates names, enforces the per-unit
+* version stamp in `units`, and ensures the unit's record tables.
+*/
+var SqliteStorageBackend = class {
+	/** The key-value facet; the only shape this backend serves. */
+	kv = { open: (descriptor) => this.openUnit(descriptor) };
+	ready;
+	/** Open (or still-opening) units by name; presence is the double-open guard. */
+	units = /* @__PURE__ */ new Map();
+	closing;
+	/**
+	* @param config - Validated plugin configuration.
+	*/
+	constructor(config) {
+		this.ready = openDatabase(config.path, config.journalMode);
+		this.ready.catch(() => {});
+	}
+	openUnit(descriptor) {
+		if (this.closing !== void 0) return Promise.reject(new StorageError("closed", "sqlite storage backend is closed"));
+		if (!UNIT_NAME_RE.test(descriptor.name)) return Promise.reject(/* @__PURE__ */ new Error(`kv unit name '${descriptor.name}' violates ${UNIT_NAME_RE}`));
+		for (const table of descriptor.tables) if (!UNIT_NAME_RE.test(table)) return Promise.reject(/* @__PURE__ */ new Error(`kv table name '${table}' in unit '${descriptor.name}' violates ${UNIT_NAME_RE}`));
+		if (this.units.has(descriptor.name)) return Promise.reject(/* @__PURE__ */ new Error(`kv unit '${descriptor.name}' is already open (double-open is a caller bug)`));
+		const pending = this.materializeUnit(descriptor);
+		this.units.set(descriptor.name, pending);
+		pending.catch(() => this.units.delete(descriptor.name));
+		return pending;
+	}
+	async materializeUnit(descriptor) {
+		const db = await this.ready;
+		const row = db.prepare("SELECT version FROM units WHERE name = ?").get(descriptor.name);
+		if (row === void 0) db.prepare("INSERT INTO units (name, version) VALUES (?, ?)").run(descriptor.name, descriptor.version);
+		else if (row.version !== descriptor.version) throw new StorageError("version-mismatch", `kv unit '${descriptor.name}' is stamped version ${row.version} on the medium, incompatible with descriptor version ${descriptor.version}`);
+		for (const table of descriptor.tables) db.exec(`
+        CREATE TABLE IF NOT EXISTS "${recordTableName(descriptor.name, table)}" (
+          key   TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        ) STRICT
+      `);
+		return new SqliteKvUnit(db, descriptor, () => {
+			this.units.delete(descriptor.name);
+		});
+	}
+	/**
+	* Close every open unit and release the database. Idempotent; concurrent
+	* and repeated calls resolve once teardown finishes.
+	* @returns resolution after the medium is released.
+	*/
+	close() {
+		this.closing ??= this.doClose();
+		return this.closing;
+	}
+	async doClose() {
+		let db;
+		try {
+			db = await this.ready;
+		} catch {
+			return;
+		}
+		for (const pending of [...this.units.values()]) await (await pending.catch(() => void 0))?.close();
+		db.close();
+	}
+};
+/**
+* Register the SQLite backend as `sqlite` on the storage hub. The disposer
+* unregisters the name first, then closes the backend.
+* @param ctx - Plugin context (must inject `storage`).
+* @param config - Validated plugin configuration.
+*/
+function apply(ctx, config) {
+	const backend = new SqliteStorageBackend(config);
+	ctx.effect(() => {
+		const dispose = ctx.storage.backend.register("sqlite", backend);
+		return async () => {
+			dispose();
+			await backend.close();
+		};
+	}, "storage-sqlite.registerBackend");
+	ctx.provide(storageBackendServiceKey("sqlite"), backend);
+}
+//#endregion
+export { Config, STORAGE_SQLITE_SCHEMA_VERSION, SqliteStorageBackend, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-storage-sqlite`.
+* @module @deepseek-ai/dsh-storage-sqlite/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-storage-sqlite";
+/** Cordis companion plugin name. */
+const name = "storage-sqlite-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: schema-version and unit-version consistency are
+* open-time checks that reject before a unit exists, and durability needs the
+* backend round-trip tests in the shared KV conformance suite; this package
+* exposes no continuously observable in-process relation.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * SQLite storage backend for the storage hub: one database file hosts every
+ * routed unit, document-per-row (`key TEXT` / `value TEXT` JSON). Registers
+ * as backend `sqlite`; the disposer unregisters first, then closes the medium.
+ * @module @deepseek-ai/dsh-storage-sqlite
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { KvFacet, StorageBackend } from '@deepseek-ai/dsh-storage';
+import { type JournalMode } from './schema.ts';
+export { STORAGE_SQLITE_SCHEMA_VERSION, type JournalMode } from './schema.ts';
+/** Cordis plugin name. */
+export declare const name = "storage-sqlite";
+/** The backend registers on the storage hub. */
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * Filesystem path to the SQLite database file. The special value `:memory:`
+     * opens an in-process database (tests). On filesystems with POSIX modes,
+     * missing directories and databases are created owner-only; existing path
+     * modes are preserved. Filesystem setup errors other than an existing
+     * database fail the open. The backend does not protect confidentiality or
+     * integrity when another principal can replace the database entry in its
+     * parent directory.
+     */
+    path: string;
+    /**
+     * SQLite `journal_mode` pragma. `wal` (the default) suits local disks; pick
+     * a rollback-journal mode (`delete`/`truncate`/`persist`) on filesystems
+     * where WAL's shared-memory files do not work (network mounts). See
+     * {@link JournalMode}.
+     */
+    journalMode?: JournalMode;
+}
+/** Schemastery validator for {@link Config}. */
+export declare const Config: z<Config>;
+/**
+ * The SQLite {@link StorageBackend}. Owns one `DatabaseSync` connection and
+ * the open-unit table; `kv.open` validates names, enforces the per-unit
+ * version stamp in `units`, and ensures the unit's record tables.
+ */
+export declare class SqliteStorageBackend implements StorageBackend {
+    /** The key-value facet; the only shape this backend serves. */
+    readonly kv: KvFacet;
+    private readonly ready;
+    /** Open (or still-opening) units by name; presence is the double-open guard. */
+    private readonly units;
+    private closing;
+    /**
+     * @param config - Validated plugin configuration.
+     */
+    constructor(config: Config);
+    private openUnit;
+    private materializeUnit;
+    /**
+     * Close every open unit and release the database. Idempotent; concurrent
+     * and repeated calls resolve once teardown finishes.
+     * @returns resolution after the medium is released.
+     */
+    close(): Promise<void>;
+    private doClose;
+}
+/**
+ * Register the SQLite backend as `sqlite` on the storage hub. The disposer
+ * unregisters the name first, then closes the backend.
+ * @param ctx - Plugin context (must inject `storage`).
+ * @param config - Validated plugin configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-storage-sqlite`.
+ * @module @deepseek-ai/dsh-storage-sqlite/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "storage-sqlite-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/schema.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Schema + open-time helpers for the SQLite storage backend: the physical
+ * layout version, the database open/configure sequence (permissions, pragmas,
+ * version stamp/reject), and the unit metadata tables. Unit record tables are
+ * created per descriptor in `unit.ts`.
+ * @module @deepseek-ai/dsh-storage-sqlite/schema
+ */
+import { DatabaseSync } from 'node:sqlite';
+/**
+ * The on-disk physical layout version, stored in `PRAGMA user_version`.
+ * Orthogonal to each unit's own `version` (stamped per unit in the `units`
+ * row). Bumped only on a breaking change to the table layout; any other
+ * stamped version rejects — this unreleased format has no migrations.
+ */
+export declare const STORAGE_SQLITE_SCHEMA_VERSION = 1;
+/**
+ * Journal modes the backend will run under. `wal` is the default; the
+ * rollback-journal modes (`delete`/`truncate`/`persist`) exist for
+ * filesystems where WAL's shared-memory files do not work (network mounts).
+ * `memory`/`off` are excluded: dropping journal durability silently
+ * contradicts the durability clause of the KV backend contract.
+ */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist';
+/**
+ * Open the database and apply its schema and pragmas. Missing directories and
+ * database files are created owner-only (`:memory:` skips filesystem setup).
+ * A zero `user_version` is stamped with {@link STORAGE_SQLITE_SCHEMA_VERSION};
+ * every other non-current version rejects rather than being migrated in place.
+ * @param path - the SQLite database file to open, or `:memory:`.
+ * @param journalMode - validated journal pragma.
+ * @returns the open handle with pragmas applied and the unit metadata tables ensured.
+ */
+export declare function openDatabase(path: string, journalMode: JournalMode): Promise<DatabaseSync>;
+/**
+ * Physical table name for one unit table. Both segments are validated against
+ * `UNIT_NAME_RE` before reaching this, so the result is safe to interpolate
+ * into DDL and prepared-statement text.
+ * @param unit - Validated unit name.
+ * @param table - Validated table name.
+ * @returns the `u_<unit>_<table>` identifier.
+ */
+export declare function recordTableName(unit: string, table: string): string;
+//# sourceMappingURL=schema.d.ts.map

package/lib/types/unit.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One opened SQLite KV unit: prepared per-table statements over the
+ * `u_<unit>_<table>` record tables plus this unit's row in the shared
+ * `unit_globals` table. Each primitive is a single statement, so atomicity
+ * comes from SQLite itself — no explicit transactions, and no write queue
+ * (write ordering is the caller's responsibility per the KV contract).
+ * @module @deepseek-ai/dsh-storage-sqlite/unit
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { KvUnit, KvUnitDescriptor } from '@deepseek-ai/dsh-storage';
+/**
+ * The SQLite {@link KvUnit}. Constructed by the backend AFTER the unit's
+ * record tables exist; statements are prepared once here and reused for every
+ * primitive. Values are stored as JSON text in the `value` column.
+ */
+export declare class SqliteKvUnit implements KvUnit {
+    private readonly descriptor;
+    private readonly onClose;
+    private readonly tables;
+    private readonly globalUpsert;
+    private readonly globalSelect;
+    private closed;
+    /**
+     * @param db - Open database handle owned by the backend (never closed here).
+     * @param descriptor - Validated descriptor whose record tables already exist.
+     * @param onClose - Backend callback releasing this unit's open-name slot.
+     */
+    constructor(db: DatabaseSync, descriptor: KvUnitDescriptor, onClose: () => void);
+    loadAll(): Promise<{
+        tables: Record<string, Record<string, unknown>>;
+        global: unknown;
+    }>;
+    /** Parse one stored value column, mapping bad JSON to `malformed-medium`. */
+    private parseValue;
+    putRecord(table: string, key: string, value: unknown): Promise<void>;
+    deleteRecord(table: string, key: string): Promise<void>;
+    setGlobal(value: unknown): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Run one synchronous primitive behind the closed guard, mapping a throw to
+     * a rejection so the Promise-returning contract never throws synchronously.
+     */
+    private settle;
+    private ensureOpen;
+    private statementsFor;
+}
+//# sourceMappingURL=unit.d.ts.map

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deepseek-ai/dsh-storage-sqlite",
+  "description": "SQLite storage backend (kv facet) for the DeepSeek Harness storage hub",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/storage/storage-sqlite"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}