@qilin-agent/storage-sqlite 0.0.0-stage → 3.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 kkutysllb
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,64 @@
1
+ # Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
2
+ # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
3
+ # After editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write packages/storage/storage-sqlite/README.md
5
+ /:
6
+ en: 07adf973ef2924fb
7
+ zh: dbc6a9255d76b7e4
8
+ /qilin-storage-sqlite:
9
+ en: 772af4c4cd8554d9
10
+ zh: 1a035269cec28ff7
11
+ /qilin-storage-sqlite/summary:
12
+ en: 8e38efc1d77eca8b
13
+ zh: cca2fec8e7ff8c2b
14
+ /qilin-storage-sqlite/table-of-contents:
15
+ en: d152484eb41ac6b4
16
+ zh: 09388d293f9be9cb
17
+ /qilin-storage-sqlite/use-this-package:
18
+ en: 98de508e10f22c1e
19
+ zh: 1e7d0cadc10cba8d
20
+ /qilin-storage-sqlite/use-this-package/when-to-choose-it:
21
+ en: 8e1ba279af55e197
22
+ zh: 7dfad7470534de6c
23
+ /qilin-storage-sqlite/use-this-package/configuration:
24
+ en: 6d613bc82795be42
25
+ zh: b4d4e9ac09300233
26
+ /qilin-storage-sqlite/use-this-package/observable-behavior:
27
+ en: b260d7bdf7971f9d
28
+ zh: 22dd2f633f507545
29
+ /qilin-storage-sqlite/understand-the-implementation:
30
+ en: 6867b52cbb94e572
31
+ zh: 187d5d61980c8fe7
32
+ /qilin-storage-sqlite/understand-the-implementation/design-concept:
33
+ en: 54ee8d9d7746e82d
34
+ zh: 2cc9f29ebcc29adc
35
+ /qilin-storage-sqlite/understand-the-implementation/open-sequence:
36
+ en: 50d85e8d8e8b5bc1
37
+ zh: 2a7067bd7fb47b35
38
+ /qilin-storage-sqlite/understand-the-implementation/source-map:
39
+ en: 79780e581c765030
40
+ zh: fa2bb0eaf915aab6
41
+ /qilin-storage-sqlite/further-exploration:
42
+ en: 26308518b12a7833
43
+ zh: 3cb9e88930a07d8f
44
+ /qilin-storage-sqlite/model-experience:
45
+ en: 215e7ba838619b7b
46
+ zh: a311da3843709f90
47
+ /qilin-storage-sqlite/model-experience/stored-domain-records:
48
+ en: c5d5ffaf6b114f3e
49
+ zh: 97db23b0b14ff1c0
50
+ /qilin-storage-sqlite/model-experience/stored-domain-records/what-the-model-sees:
51
+ en: d0798e9e30583b55
52
+ zh: 968f7f595b4bf1ff
53
+ /qilin-storage-sqlite/model-experience/stored-domain-records/token-effect:
54
+ en: 592ed887c69e5c46
55
+ zh: cb9be9de6e38db55
56
+ /qilin-storage-sqlite/model-experience/stored-domain-records/kv-cache-effect:
57
+ en: c13c59d13a5f1651
58
+ zh: 5aab838ae3ff5324
59
+ /qilin-storage-sqlite/known-limitations-and-deferred-work:
60
+ en: c24fe7a01bc44ed3
61
+ zh: 69638d0692bdb637
62
+ /qilin-storage-sqlite/known-limitations-and-deferred-work/dev-note:
63
+ en: e67f633dc6fe7773
64
+ zh: 3bb0c20c93f16f98
package/README.md CHANGED
@@ -1,3 +1,141 @@
1
- # Temporary Holding Version
1
+ ---
2
+ description: "SQLite storage backend for hosts and maintainers choosing, configuring, or debugging document-per-row KV storage in one database file."
3
+ kind: "package-reference"
4
+ ---
2
5
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
6
+ # @qilin-agent/storage-sqlite
7
+
8
+ English | [中文](README.zh.md)
9
+
10
+ ## Summary
11
+
12
+ `qilin-storage-sqlite` is a storage backend that hosts every routed unit in one SQLite database file, storing each record as one JSON document per row, registered as backend `sqlite`. A single record update touches exactly one row, which is what makes this the right medium for high-frequency, point-sized writes. Choose it when a domain's data changes often or the deployment prefers one queryable database; choose the JSON backend when the data should be readable as plain files. The backend is host-side only: it contributes no prompt, tool, or schema, so the model and the agent loop never see it.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
27
+
28
+ Use this package when a composition keeps frequently updated domain data in one database: route the relevant domains to this backend and each unit materializes as tables in the configured database file.
29
+
30
+ ### When to choose it
31
+
32
+ Choose it when writes are frequent and point-sized — each key maps to exactly one row, so updating one record touches one row instead of rewriting a whole file. Choose the JSON backend when humans inspect or edit the stored data as plain files. The synchronous `node:sqlite` driver blocks the JavaScript thread for the duration of each single-statement call, which is fine at domain-data scale but worth accounting for at high write rates.
33
+
34
+ ### Configuration
35
+
36
+ Two fields: the database path and the journal mode. `:memory:` opens an in-process database whose contents disappear with the process.
37
+
38
+ ```yaml
39
+ - name: '@qilin-agent/storage'
40
+ - name: '@qilin-agent/storage-sqlite'
41
+ config:
42
+ path: /var/lib/qilin/data.db
43
+ - name: '@qilin-agent/storage-domain'
44
+ config:
45
+ backend: sqlite
46
+ ```
47
+
48
+ | Field | Default | Meaning |
49
+ |---|---|---|
50
+ | `path` | required | SQLite database file path, or `:memory:` |
51
+ | `journalMode` | `wal` | Journal mode: `wal`, `delete`, `truncate`, or `persist` |
52
+
53
+ `wal` suits local disks; a rollback-journal mode (`delete`/`truncate`/`persist`) fits filesystems where WAL's shared-memory files do not work, such as network mounts. The generated [configuration catalog](../../../docs/config-catalog.md#qilin-agentstorage-sqlite) is the exhaustive source for every accepted field and its JSDoc.
54
+
55
+ ### Observable behavior
56
+
57
+ Missing directories and database files are created owner-only (`0o700`/`0o600`); an existing database keeps its modes. A unit whose stored format version differs from its descriptor rejects `version-mismatch`, and a database stamped with a physical layout version other than the current one rejects outright — no migration, pre-release stance. Failures carry stable `StorageError` codes, and writes are durable once resolved.
58
+
59
+ -----
60
+
61
+ <a id="understand-the-implementation"></a>
62
+ ## Understand the implementation
63
+
64
+ <details>
65
+ <summary>Implementation internals — click to expand</summary>
66
+
67
+ The backend is a document-per-row layout over one `node:sqlite` connection, designed so a per-key update is a single prepared statement.
68
+
69
+ ### Design concept
70
+
71
+ - **Document per row.** Each unit table becomes a physical STRICT table `u_<unit>_<table> (key TEXT PRIMARY KEY, value TEXT)` whose `value` column holds the record's JSON text; the global singleton lives in a shared `unit_globals` table. One key update touches exactly one row — the reason to route a high-churn domain here.
72
+ - **Single-statement atomicity.** Every write primitive is one prepared statement, so SQLite's per-statement atomicity satisfies the KV contract without explicit transactions; write ordering stays the caller's responsibility (the domain layer's write chain).
73
+ - **Names validated before DDL.** Unit and table names must match `UNIT_NAME_RE` before they reach DDL, so no external input is ever interpolated into SQL identifiers.
74
+ - **Versions fail loud.** The physical layout version lives in `PRAGMA user_version` (fresh databases stamp it last); unit format versions live in the `units` table. Any other stamped value rejects — no migrations.
75
+
76
+ ### Open sequence
77
+
78
+ Opening the database creates the parent as `0o700`, exclusively creates a missing file as `0o600`, applies `PRAGMA foreign_keys = ON` and the journal mode, checks `user_version`, creates the `units` and `unit_globals` metadata tables, and stamps fresh databases last so a failure leaves the medium unstamped.
79
+
80
+ ### Source map
81
+
82
+ | File | Role |
83
+ |---|---|
84
+ | [`src/index.ts`](src/index.ts) | Plugin entry: backend registration, `path`/`journalMode` config, unit table |
85
+ | [`src/schema.ts`](src/schema.ts) | Open sequence, physical layout version, metadata tables, record table naming |
86
+ | [`src/unit.ts`](src/unit.ts) | One opened unit: prepared statements, JSON value parse, close |
87
+
88
+ </details>
89
+
90
+ -----
91
+
92
+ <a id="further-exploration"></a>
93
+ ## Further Exploration
94
+
95
+ Read these pages when this backend's view is not enough: the subsystem reference is the authoritative contract, and the sibling backend shows the alternative medium.
96
+
97
+ - [Storage subsystem](../../../docs/subsystems/storage.md) — the backend contract, domain semantics, and generated API.
98
+ - [Storage package map](../README.md) — the family's packages and their repository position.
99
+ - [JSON storage backend](../storage-json/README.md) — the human-readable medium for small, inspectable data.
100
+ - [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) — the design behind the backend family and the deferred session-backend migration.
101
+
102
+ -----
103
+
104
+ <a id="model-experience"></a>
105
+ ## Model Experience
106
+
107
+ ### Stored domain records
108
+
109
+ #### What the model sees
110
+
111
+ Nothing. This backend contributes no prompt, tool, or schema; it persists non-session domain data behind `ctx.storage` for host-side consumers only.
112
+
113
+ #### Token effect
114
+
115
+ Zero live-request tokens.
116
+
117
+ #### KV Cache effect
118
+
119
+ None — the backend never touches live request prefixes.
120
+
121
+ ## Known Limitations and Deferred Work
122
+
123
+ <a id="known-limitations-and-deferred-work"></a>
124
+
125
+
126
+ These limits define when this backend is a poor fit or needs special operational care. They are current package constraints, not a task backlog.
127
+
128
+ - **Synchronous driver blocks the event loop** — each write is a synchronous `DatabaseSync` call; the block lasts a single statement, which is acceptable at domain-data scale.
129
+ - **No busy-wait or retry policy** — a competing connection holding a write lock rejects the operation immediately instead of waiting; the domain layer's write chain serializes writes within one process, and cross-process coordination is out of scope.
130
+ - **Only the current physical layout version opens** — any other stamped `user_version` is rejected rather than migrated (pre-release stance).
131
+ - **Open sequence duplicated with the query provider** — `openDatabase` and `session-query-sqlite` both enforce SQLite file ownership, but each package owns a distinct application identity and schema; no shared medium helper couples them.
132
+
133
+ <a id="dev-note"></a>
134
+ ### Dev Note
135
+
136
+ <details>
137
+ <summary>Working context for maintainers — click to expand</summary>
138
+
139
+ None.
140
+
141
+ </details>
package/README.zh.md ADDED
@@ -0,0 +1,141 @@
1
+ ---
2
+ description: "SQLite 存储后端:面向在单个数据库文件中选择、配置或排查按行存储文档的 KV 存储的宿主与维护者。"
3
+ kind: "package-reference"
4
+ ---
5
+
6
+ # @qilin-agent/storage-sqlite
7
+
8
+ [English](README.md) | 中文
9
+
10
+ ## 概述
11
+
12
+ `qilin-storage-sqlite` 是一个存储后端:把每个已路由单元托管在同一个 SQLite 数据库文件中,每条记录按行存储一份 JSON 文档,注册为后端 `sqlite`。单条记录更新恰好触碰一行,这正是它适合高频定点写入的原因。当领域数据变动频繁、或部署偏好单一可查询数据库时选择它;当数据需要以纯文本文件形式可读时选择 JSON 后端。本后端只面向宿主侧:它不贡献提示词、工具或 schema,因此模型与 agent loop(智能体循环)永远不会看到它。
13
+
14
+ ## 目录
15
+
16
+ - [使用本包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [进一步探索](#further-exploration)
19
+ - [模型体验](#model-experience)
20
+ - [已知限制与延期工作](#known-limitations-and-deferred-work)
21
+ - [开发备注](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## 使用本包
27
+
28
+ 当组合把频繁更新的领域数据保存在一个数据库中时使用本包:把相关领域路由到此后端,每个单元即作为表物化在配置的数据库文件中。
29
+
30
+ ### 何时选择
31
+
32
+ 当写入频繁且为定点更新时选择它——每个键恰好映射到一行,因此更新一条记录只触碰一行,而不是重写整个文件。当人类需要以纯文本文件查看或编辑已存数据时选择 JSON 后端。同步的 `node:sqlite` 驱动会在每条单语句调用期间阻塞 JavaScript 线程,这在领域数据规模下可以接受,但高写入率时值得纳入考量。
33
+
34
+ ### 配置
35
+
36
+ 两个字段:数据库路径与 journal mode。`:memory:` 打开一个进程内数据库,其内容随进程消失。
37
+
38
+ ```yaml
39
+ - name: '@qilin-agent/storage'
40
+ - name: '@qilin-agent/storage-sqlite'
41
+ config:
42
+ path: /var/lib/qilin/data.db
43
+ - name: '@qilin-agent/storage-domain'
44
+ config:
45
+ backend: sqlite
46
+ ```
47
+
48
+ | 字段 | 默认值 | 含义 |
49
+ |---|---|---|
50
+ | `path` | 必填 | SQLite 数据库文件路径,或 `:memory:` |
51
+ | `journalMode` | `wal` | Journal mode:`wal`、`delete`、`truncate` 或 `persist` |
52
+
53
+ `wal` 适合本地磁盘;回滚日志模式(`delete`/`truncate`/`persist`)适合 WAL 共享内存文件不可用的文件系统,例如网络挂载。生成的[配置目录](../../../docs/config-catalog.zh.md#qilin-agentstorage-sqlite)是每个受支持字段及其 JSDoc 的穷尽式真源。
54
+
55
+ ### 可观察行为
56
+
57
+ 缺失的目录与数据库文件会以仅所有者可访问的权限创建(`0o700`/`0o600`);已有数据库保持其既有模式。已存格式版本与描述符不同的单元拒绝 `version-mismatch`,盖有非当前物理布局版本的数据库会直接拒绝——不做迁移,预发布立场。失败携带稳定的 `StorageError` 代码,写入操作完成后即已持久化。
58
+
59
+ -----
60
+
61
+ <a id="understand-the-implementation"></a>
62
+ ## 理解实现
63
+
64
+ <details>
65
+ <summary>实现细节——点击展开</summary>
66
+
67
+ 本后端是在单个 `node:sqlite` 连接之上的文档按行布局,设计目标是让每次按键更新都是一条预处理语句。
68
+
69
+ ### 设计理念
70
+
71
+ - **每行一份文档。** 每个单元表都变成一张物理 STRICT 表 `u_<unit>_<table> (key TEXT PRIMARY KEY, value TEXT)`,其 `value` 列保存记录的 JSON 文本;全局单例存放在共享的 `unit_globals` 表中。一个键的更新恰好触碰一行——这就是把高频变更领域路由到这里的原因。
72
+ - **单语句原子性。** 每个写入原语都是一条预处理语句,因此 SQLite 的逐语句原子性无需显式事务即可满足 KV 约定;写入顺序仍由调用方负责(领域层的写入链)。
73
+ - **名称在 DDL 之前校验。** 单元名与表名在进入 DDL 之前必须匹配 `UNIT_NAME_RE`,因此任何外部输入都不会被插值进 SQL 标识符。
74
+ - **版本明确报错。** 物理布局版本存放在 `PRAGMA user_version`(全新数据库最后盖戳);单元格式版本存放在 `units` 表中。任何其他已标记值都会被拒绝——不做迁移。
75
+
76
+ ### 打开顺序
77
+
78
+ 打开数据库时会以 `0o700` 创建父目录、以 `0o600` 独占创建缺失文件、应用 `PRAGMA foreign_keys = ON` 与 journal mode、检查 `user_version`、创建 `units` 与 `unit_globals` 元数据表,并在最后给全新数据库盖戳,让失败留下未盖戳的介质。
79
+
80
+ ### 源码地图
81
+
82
+ | 文件 | 职责 |
83
+ |---|---|
84
+ | [`src/index.ts`](src/index.ts) | 插件入口:后端注册、`path`/`journalMode` 配置、单元表 |
85
+ | [`src/schema.ts`](src/schema.ts) | 打开顺序、物理布局版本、元数据表、记录表命名 |
86
+ | [`src/unit.ts`](src/unit.ts) | 一个已打开单元:预处理语句、JSON 值解析、关闭 |
87
+
88
+ </details>
89
+
90
+ -----
91
+
92
+ <a id="further-exploration"></a>
93
+ ## 进一步探索
94
+
95
+ 当本后端视角不够用时阅读以下页面:子系统参考是权威约定,兄弟后端展示了另一种介质。
96
+
97
+ - [存储子系统](../../../docs/subsystems/storage.zh.md)——后端约定、领域语义与生成的 API。
98
+ - [存储包映射](../README.zh.md)——家族的各包及其在仓库中的位置。
99
+ - [JSON 存储后端](../storage-json/README.zh.md)——面向小而可检查数据的人类可读介质。
100
+ - [领域 KV 存储 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)——后端家族背后的设计与被推迟的会话后端迁移。
101
+
102
+ -----
103
+
104
+ <a id="model-experience"></a>
105
+ ## 模型体验
106
+
107
+ ### 已存领域记录
108
+
109
+ #### 模型看到什么
110
+
111
+ 无。本后端不贡献提示词、工具或 schema;它在 `ctx.storage` 后面持久化非会话领域数据,只供宿主侧消费方使用。
112
+
113
+ #### Token 影响
114
+
115
+ 实时请求 token 为零。
116
+
117
+ #### KV Cache 影响
118
+
119
+ 无:本后端从不触碰实时请求前缀。
120
+
121
+ ## 已知限制与延期工作
122
+
123
+ <a id="known-limitations-and-deferred-work"></a>
124
+
125
+
126
+ 这些限制说明本后端何时不合适,或何时需要特别的运维注意。它们是当前包约束,不是任务积压。
127
+
128
+ - **同步驱动阻塞事件循环**——每次写入都是一次同步 `DatabaseSync` 调用;阻塞只持续一条语句,在领域数据规模下可以接受。
129
+ - **没有忙等待或重试策略**——持有写锁的竞争连接会立即拒绝操作,而不是等待;领域层的写入链在单进程内串行化写入,跨进程协调不在范围内。
130
+ - **只打开当前的物理布局版本**——任何其他已标记的 `user_version` 都会被拒绝而不是迁移(预发布立场)。
131
+ - **打开顺序与查询提供方重复**——`openDatabase` 与 `session-query-sqlite` 都强制执行 SQLite 文件所有权约束,但两个包各自拥有不同的应用标识与 schema;没有共享介质辅助模块将二者耦合。
132
+
133
+ <a id="dev-note"></a>
134
+ ### 开发备注
135
+
136
+ <details>
137
+ <summary>维护者的工作上下文——点击展开</summary>
138
+
139
+ 无。
140
+
141
+ </details>
package/lib/index.js ADDED
@@ -0,0 +1,308 @@
1
+ import z from "@qilin-agent/schemastery";
2
+ import { StorageError, UNIT_NAME_RE, storageBackendServiceKey } from "@qilin-agent/storage";
3
+ import { DatabaseSync } from "node:sqlite";
4
+ import { mkdir, open } from "node:fs/promises";
5
+ import { dirname, resolve } from "node:path";
6
+ //#region lib/types/schema.js
7
+ /**
8
+ * Schema + open-time helpers for the SQLite storage backend: the physical
9
+ * layout version, the database open/configure sequence (permissions, pragmas,
10
+ * version stamp/reject), and the unit metadata tables. Unit record tables are
11
+ * created per descriptor in `unit.ts`.
12
+ * @module @qilin-agent/storage-sqlite/schema
13
+ */
14
+ /**
15
+ * The on-disk physical layout version, stored in `PRAGMA user_version`.
16
+ * Orthogonal to each unit's own `version` (stamped per unit in the `units`
17
+ * row). Bumped only on a breaking change to the table layout; any other
18
+ * stamped version rejects — this unreleased format has no migrations.
19
+ */
20
+ const STORAGE_SQLITE_SCHEMA_VERSION = 1;
21
+ /**
22
+ * Exclusively create a missing database file with owner-only permissions.
23
+ * Existing files retain their modes, and errors other than `EEXIST` propagate.
24
+ * `DatabaseSync` reopens by path, so this does not protect confidentiality or
25
+ * integrity when another principal can replace the database entry in its
26
+ * parent directory.
27
+ */
28
+ async function createDatabaseFile(path) {
29
+ try {
30
+ await (await open(path, "wx", 384)).close();
31
+ } catch (error) {
32
+ if (error.code !== "EEXIST") throw error;
33
+ }
34
+ }
35
+ /**
36
+ * Open the database and apply its schema and pragmas. Missing directories and
37
+ * database files are created owner-only (`:memory:` skips filesystem setup).
38
+ * A zero `user_version` is stamped with {@link STORAGE_SQLITE_SCHEMA_VERSION};
39
+ * every other non-current version rejects rather than being migrated in place.
40
+ * @param path - the SQLite database file to open, or `:memory:`.
41
+ * @param journalMode - validated journal pragma.
42
+ * @returns the open handle with pragmas applied and the unit metadata tables ensured.
43
+ */
44
+ async function openDatabase(path, journalMode) {
45
+ const actual = path === ":memory:" ? path : resolve(path);
46
+ if (actual !== ":memory:") {
47
+ await mkdir(dirname(actual), {
48
+ recursive: true,
49
+ mode: 448
50
+ });
51
+ await createDatabaseFile(actual);
52
+ }
53
+ const db = new DatabaseSync(actual);
54
+ try {
55
+ configureDatabase(db, actual, journalMode);
56
+ return db;
57
+ } catch (error) {
58
+ db.close();
59
+ throw error;
60
+ }
61
+ }
62
+ function configureDatabase(db, path, journalMode) {
63
+ db.exec("PRAGMA foreign_keys = ON");
64
+ db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`);
65
+ const { user_version: onDisk } = db.prepare("PRAGMA user_version").get();
66
+ if (onDisk !== 0 && onDisk !== 1) throw new StorageError("version-mismatch", `storage database at "${path}" has schema version ${onDisk}, incompatible with this build (1)`);
67
+ db.exec(`
68
+ CREATE TABLE IF NOT EXISTS units (
69
+ name TEXT PRIMARY KEY,
70
+ version INTEGER NOT NULL
71
+ ) STRICT
72
+ `);
73
+ db.exec(`
74
+ CREATE TABLE IF NOT EXISTS unit_globals (
75
+ unit TEXT PRIMARY KEY REFERENCES units(name),
76
+ value TEXT NOT NULL
77
+ ) STRICT
78
+ `);
79
+ if (onDisk === 0) db.exec(`PRAGMA user_version = 1`);
80
+ }
81
+ /**
82
+ * Physical table name for one unit table. Both segments are validated against
83
+ * `UNIT_NAME_RE` before reaching this, so the result is safe to interpolate
84
+ * into DDL and prepared-statement text.
85
+ * @param unit - Validated unit name.
86
+ * @param table - Validated table name.
87
+ * @returns the `u_<unit>_<table>` identifier.
88
+ */
89
+ function recordTableName(unit, table) {
90
+ return `u_${unit}_${table}`;
91
+ }
92
+ //#endregion
93
+ //#region lib/types/unit.js
94
+ /**
95
+ * One opened SQLite KV unit: prepared per-table statements over the
96
+ * `u_<unit>_<table>` record tables plus this unit's row in the shared
97
+ * `unit_globals` table. Each primitive is a single statement, so atomicity
98
+ * comes from SQLite itself — no explicit transactions, and no write queue
99
+ * (write ordering is the caller's responsibility per the KV contract).
100
+ * @module @qilin-agent/storage-sqlite/unit
101
+ */
102
+ /**
103
+ * The SQLite {@link KvUnit}. Constructed by the backend AFTER the unit's
104
+ * record tables exist; statements are prepared once here and reused for every
105
+ * primitive. Values are stored as JSON text in the `value` column.
106
+ */
107
+ var SqliteKvUnit = class {
108
+ descriptor;
109
+ onClose;
110
+ tables = /* @__PURE__ */ new Map();
111
+ globalUpsert;
112
+ globalSelect;
113
+ closed = false;
114
+ /**
115
+ * @param db - Open database handle owned by the backend (never closed here).
116
+ * @param descriptor - Validated descriptor whose record tables already exist.
117
+ * @param onClose - Backend callback releasing this unit's open-name slot.
118
+ */
119
+ constructor(db, descriptor, onClose) {
120
+ this.descriptor = descriptor;
121
+ this.onClose = onClose;
122
+ for (const table of descriptor.tables) {
123
+ const physical = recordTableName(descriptor.name, table);
124
+ this.tables.set(table, {
125
+ upsert: db.prepare(`INSERT INTO "${physical}" (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`),
126
+ remove: db.prepare(`DELETE FROM "${physical}" WHERE key = ?`),
127
+ selectAll: db.prepare(`SELECT key, value FROM "${physical}"`)
128
+ });
129
+ }
130
+ this.globalUpsert = descriptor.hasGlobal ? db.prepare("INSERT INTO unit_globals (unit, value) VALUES (?, ?) ON CONFLICT(unit) DO UPDATE SET value = excluded.value") : void 0;
131
+ this.globalSelect = descriptor.hasGlobal ? db.prepare("SELECT value FROM unit_globals WHERE unit = ?") : void 0;
132
+ }
133
+ loadAll() {
134
+ return this.settle(() => {
135
+ const tables = {};
136
+ for (const [name, statements] of this.tables) {
137
+ const records = Object.create(null);
138
+ for (const row of statements.selectAll.all()) records[row.key] = this.parseValue(row.value, `table '${name}' key '${row.key}'`);
139
+ tables[name] = records;
140
+ }
141
+ let global = null;
142
+ if (this.globalSelect !== void 0) {
143
+ const row = this.globalSelect.get(this.descriptor.name);
144
+ if (row !== void 0) global = this.parseValue(row.value, "global slot");
145
+ }
146
+ return {
147
+ tables,
148
+ global
149
+ };
150
+ });
151
+ }
152
+ /** Parse one stored value column, mapping bad JSON to `malformed-medium`. */
153
+ parseValue(text, slot) {
154
+ try {
155
+ return JSON.parse(text);
156
+ } catch (error) {
157
+ throw new StorageError("malformed-medium", `kv unit '${this.descriptor.name}' holds unparsable JSON at ${slot}`, { cause: error });
158
+ }
159
+ }
160
+ putRecord(table, key, value) {
161
+ return this.settle(() => {
162
+ this.statementsFor(table).upsert.run(key, JSON.stringify(value));
163
+ });
164
+ }
165
+ deleteRecord(table, key) {
166
+ return this.settle(() => {
167
+ this.statementsFor(table).remove.run(key);
168
+ });
169
+ }
170
+ setGlobal(value) {
171
+ return this.settle(() => {
172
+ if (this.globalUpsert === void 0) throw new Error(`kv unit '${this.descriptor.name}' declared no global slot`);
173
+ this.globalUpsert.run(this.descriptor.name, JSON.stringify(value));
174
+ });
175
+ }
176
+ close() {
177
+ if (!this.closed) {
178
+ this.closed = true;
179
+ this.onClose();
180
+ }
181
+ return Promise.resolve();
182
+ }
183
+ /**
184
+ * Run one synchronous primitive behind the closed guard, mapping a throw to
185
+ * a rejection so the Promise-returning contract never throws synchronously.
186
+ */
187
+ settle(operation) {
188
+ try {
189
+ this.ensureOpen();
190
+ return Promise.resolve(operation());
191
+ } catch (error) {
192
+ return Promise.reject(error instanceof Error ? error : new Error(String(error)));
193
+ }
194
+ }
195
+ ensureOpen() {
196
+ if (this.closed) throw new StorageError("closed", `kv unit '${this.descriptor.name}' is closed`);
197
+ }
198
+ statementsFor(table) {
199
+ const statements = this.tables.get(table);
200
+ if (statements === void 0) throw new Error(`kv unit '${this.descriptor.name}' declared no table '${table}'`);
201
+ return statements;
202
+ }
203
+ };
204
+ //#endregion
205
+ //#region lib/types/index.js
206
+ /**
207
+ * SQLite storage backend for the storage hub: one database file hosts every
208
+ * routed unit, document-per-row (`key TEXT` / `value TEXT` JSON). Registers
209
+ * as backend `sqlite`; the disposer unregisters first, then closes the medium.
210
+ * @module @qilin-agent/storage-sqlite
211
+ */
212
+ /** Cordis plugin name. */
213
+ const name = "storage-sqlite";
214
+ /** The backend registers on the storage hub. */
215
+ const inject = ["storage"];
216
+ /** Schemastery validator for {@link Config}. */
217
+ const Config = z.object({
218
+ path: z.string().required(),
219
+ journalMode: z.union([
220
+ "wal",
221
+ "delete",
222
+ "truncate",
223
+ "persist"
224
+ ]).default("wal")
225
+ });
226
+ /**
227
+ * The SQLite {@link StorageBackend}. Owns one `DatabaseSync` connection and
228
+ * the open-unit table; `kv.open` validates names, enforces the per-unit
229
+ * version stamp in `units`, and ensures the unit's record tables.
230
+ */
231
+ var SqliteStorageBackend = class {
232
+ /** The key-value facet; the only shape this backend serves. */
233
+ kv = { open: (descriptor) => this.openUnit(descriptor) };
234
+ ready;
235
+ /** Open (or still-opening) units by name; presence is the double-open guard. */
236
+ units = /* @__PURE__ */ new Map();
237
+ closing;
238
+ /**
239
+ * @param config - Validated plugin configuration.
240
+ */
241
+ constructor(config) {
242
+ this.ready = openDatabase(config.path, config.journalMode);
243
+ this.ready.catch(() => {});
244
+ }
245
+ openUnit(descriptor) {
246
+ if (this.closing !== void 0) return Promise.reject(new StorageError("closed", "sqlite storage backend is closed"));
247
+ if (!UNIT_NAME_RE.test(descriptor.name)) return Promise.reject(/* @__PURE__ */ new Error(`kv unit name '${descriptor.name}' violates ${UNIT_NAME_RE}`));
248
+ 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}`));
249
+ 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)`));
250
+ const pending = this.materializeUnit(descriptor);
251
+ this.units.set(descriptor.name, pending);
252
+ pending.catch(() => this.units.delete(descriptor.name));
253
+ return pending;
254
+ }
255
+ async materializeUnit(descriptor) {
256
+ const db = await this.ready;
257
+ const row = db.prepare("SELECT version FROM units WHERE name = ?").get(descriptor.name);
258
+ if (row === void 0) db.prepare("INSERT INTO units (name, version) VALUES (?, ?)").run(descriptor.name, descriptor.version);
259
+ 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}`);
260
+ for (const table of descriptor.tables) db.exec(`
261
+ CREATE TABLE IF NOT EXISTS "${recordTableName(descriptor.name, table)}" (
262
+ key TEXT PRIMARY KEY,
263
+ value TEXT NOT NULL
264
+ ) STRICT
265
+ `);
266
+ return new SqliteKvUnit(db, descriptor, () => {
267
+ this.units.delete(descriptor.name);
268
+ });
269
+ }
270
+ /**
271
+ * Close every open unit and release the database. Idempotent; concurrent
272
+ * and repeated calls resolve once teardown finishes.
273
+ * @returns resolution after the medium is released.
274
+ */
275
+ close() {
276
+ this.closing ??= this.doClose();
277
+ return this.closing;
278
+ }
279
+ async doClose() {
280
+ let db;
281
+ try {
282
+ db = await this.ready;
283
+ } catch {
284
+ return;
285
+ }
286
+ for (const pending of [...this.units.values()]) await (await pending.catch(() => void 0))?.close();
287
+ db.close();
288
+ }
289
+ };
290
+ /**
291
+ * Register the SQLite backend as `sqlite` on the storage hub. The disposer
292
+ * unregisters the name first, then closes the backend.
293
+ * @param ctx - Plugin context (must inject `storage`).
294
+ * @param config - Validated plugin configuration.
295
+ */
296
+ function apply(ctx, config) {
297
+ const backend = new SqliteStorageBackend(config);
298
+ ctx.effect(() => {
299
+ const dispose = ctx.storage.backend.register("sqlite", backend);
300
+ return async () => {
301
+ dispose();
302
+ await backend.close();
303
+ };
304
+ }, "storage-sqlite.registerBackend");
305
+ ctx.provide(storageBackendServiceKey("sqlite"), backend);
306
+ }
307
+ //#endregion
308
+ export { Config, STORAGE_SQLITE_SCHEMA_VERSION, SqliteStorageBackend, apply, inject, name };
@@ -0,0 +1,71 @@
1
+ /**
2
+ * SQLite storage backend for the storage hub: one database file hosts every
3
+ * routed unit, document-per-row (`key TEXT` / `value TEXT` JSON). Registers
4
+ * as backend `sqlite`; the disposer unregisters first, then closes the medium.
5
+ * @module @qilin-agent/storage-sqlite
6
+ */
7
+ import type { Context } from '@qilin-agent/kylin';
8
+ import z from '@qilin-agent/schemastery';
9
+ import type { KvFacet, StorageBackend } from '@qilin-agent/storage';
10
+ import { type JournalMode } from './schema.ts';
11
+ export { STORAGE_SQLITE_SCHEMA_VERSION, type JournalMode } from './schema.ts';
12
+ /** Cordis plugin name. */
13
+ export declare const name = "storage-sqlite";
14
+ /** The backend registers on the storage hub. */
15
+ export declare const inject: string[];
16
+ /** Plugin configuration. */
17
+ export interface Config {
18
+ /**
19
+ * Filesystem path to the SQLite database file. The special value `:memory:`
20
+ * opens an in-process database (tests). On filesystems with POSIX modes,
21
+ * missing directories and databases are created owner-only; existing path
22
+ * modes are preserved. Filesystem setup errors other than an existing
23
+ * database fail the open. The backend does not protect confidentiality or
24
+ * integrity when another principal can replace the database entry in its
25
+ * parent directory.
26
+ */
27
+ path: string;
28
+ /**
29
+ * SQLite `journal_mode` pragma. `wal` (the default) suits local disks; pick
30
+ * a rollback-journal mode (`delete`/`truncate`/`persist`) on filesystems
31
+ * where WAL's shared-memory files do not work (network mounts). See
32
+ * {@link JournalMode}.
33
+ */
34
+ journalMode?: JournalMode;
35
+ }
36
+ /** Schemastery validator for {@link Config}. */
37
+ export declare const Config: z<Config>;
38
+ /**
39
+ * The SQLite {@link StorageBackend}. Owns one `DatabaseSync` connection and
40
+ * the open-unit table; `kv.open` validates names, enforces the per-unit
41
+ * version stamp in `units`, and ensures the unit's record tables.
42
+ */
43
+ export declare class SqliteStorageBackend implements StorageBackend {
44
+ /** The key-value facet; the only shape this backend serves. */
45
+ readonly kv: KvFacet;
46
+ private readonly ready;
47
+ /** Open (or still-opening) units by name; presence is the double-open guard. */
48
+ private readonly units;
49
+ private closing;
50
+ /**
51
+ * @param config - Validated plugin configuration.
52
+ */
53
+ constructor(config: Config);
54
+ private openUnit;
55
+ private materializeUnit;
56
+ /**
57
+ * Close every open unit and release the database. Idempotent; concurrent
58
+ * and repeated calls resolve once teardown finishes.
59
+ * @returns resolution after the medium is released.
60
+ */
61
+ close(): Promise<void>;
62
+ private doClose;
63
+ }
64
+ /**
65
+ * Register the SQLite backend as `sqlite` on the storage hub. The disposer
66
+ * unregisters the name first, then closes the backend.
67
+ * @param ctx - Plugin context (must inject `storage`).
68
+ * @param config - Validated plugin configuration.
69
+ */
70
+ export declare function apply(ctx: Context, config: Config): void;
71
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Schema + open-time helpers for the SQLite storage backend: the physical
3
+ * layout version, the database open/configure sequence (permissions, pragmas,
4
+ * version stamp/reject), and the unit metadata tables. Unit record tables are
5
+ * created per descriptor in `unit.ts`.
6
+ * @module @qilin-agent/storage-sqlite/schema
7
+ */
8
+ import { DatabaseSync } from 'node:sqlite';
9
+ /**
10
+ * The on-disk physical layout version, stored in `PRAGMA user_version`.
11
+ * Orthogonal to each unit's own `version` (stamped per unit in the `units`
12
+ * row). Bumped only on a breaking change to the table layout; any other
13
+ * stamped version rejects — this unreleased format has no migrations.
14
+ */
15
+ export declare const STORAGE_SQLITE_SCHEMA_VERSION = 1;
16
+ /**
17
+ * Journal modes the backend will run under. `wal` is the default; the
18
+ * rollback-journal modes (`delete`/`truncate`/`persist`) exist for
19
+ * filesystems where WAL's shared-memory files do not work (network mounts).
20
+ * `memory`/`off` are excluded: dropping journal durability silently
21
+ * contradicts the durability clause of the KV backend contract.
22
+ */
23
+ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist';
24
+ /**
25
+ * Open the database and apply its schema and pragmas. Missing directories and
26
+ * database files are created owner-only (`:memory:` skips filesystem setup).
27
+ * A zero `user_version` is stamped with {@link STORAGE_SQLITE_SCHEMA_VERSION};
28
+ * every other non-current version rejects rather than being migrated in place.
29
+ * @param path - the SQLite database file to open, or `:memory:`.
30
+ * @param journalMode - validated journal pragma.
31
+ * @returns the open handle with pragmas applied and the unit metadata tables ensured.
32
+ */
33
+ export declare function openDatabase(path: string, journalMode: JournalMode): Promise<DatabaseSync>;
34
+ /**
35
+ * Physical table name for one unit table. Both segments are validated against
36
+ * `UNIT_NAME_RE` before reaching this, so the result is safe to interpolate
37
+ * into DDL and prepared-statement text.
38
+ * @param unit - Validated unit name.
39
+ * @param table - Validated table name.
40
+ * @returns the `u_<unit>_<table>` identifier.
41
+ */
42
+ export declare function recordTableName(unit: string, table: string): string;
43
+ //# sourceMappingURL=schema.d.ts.map
@@ -0,0 +1,47 @@
1
+ /**
2
+ * One opened SQLite KV unit: prepared per-table statements over the
3
+ * `u_<unit>_<table>` record tables plus this unit's row in the shared
4
+ * `unit_globals` table. Each primitive is a single statement, so atomicity
5
+ * comes from SQLite itself — no explicit transactions, and no write queue
6
+ * (write ordering is the caller's responsibility per the KV contract).
7
+ * @module @qilin-agent/storage-sqlite/unit
8
+ */
9
+ import type { DatabaseSync } from 'node:sqlite';
10
+ import type { KvUnit, KvUnitDescriptor } from '@qilin-agent/storage';
11
+ /**
12
+ * The SQLite {@link KvUnit}. Constructed by the backend AFTER the unit's
13
+ * record tables exist; statements are prepared once here and reused for every
14
+ * primitive. Values are stored as JSON text in the `value` column.
15
+ */
16
+ export declare class SqliteKvUnit implements KvUnit {
17
+ private readonly descriptor;
18
+ private readonly onClose;
19
+ private readonly tables;
20
+ private readonly globalUpsert;
21
+ private readonly globalSelect;
22
+ private closed;
23
+ /**
24
+ * @param db - Open database handle owned by the backend (never closed here).
25
+ * @param descriptor - Validated descriptor whose record tables already exist.
26
+ * @param onClose - Backend callback releasing this unit's open-name slot.
27
+ */
28
+ constructor(db: DatabaseSync, descriptor: KvUnitDescriptor, onClose: () => void);
29
+ loadAll(): Promise<{
30
+ tables: Record<string, Record<string, unknown>>;
31
+ global: unknown;
32
+ }>;
33
+ /** Parse one stored value column, mapping bad JSON to `malformed-medium`. */
34
+ private parseValue;
35
+ putRecord(table: string, key: string, value: unknown): Promise<void>;
36
+ deleteRecord(table: string, key: string): Promise<void>;
37
+ setGlobal(value: unknown): Promise<void>;
38
+ close(): Promise<void>;
39
+ /**
40
+ * Run one synchronous primitive behind the closed guard, mapping a throw to
41
+ * a rejection so the Promise-returning contract never throws synchronously.
42
+ */
43
+ private settle;
44
+ private ensureOpen;
45
+ private statementsFor;
46
+ }
47
+ //# sourceMappingURL=unit.d.ts.map
package/package.json CHANGED
@@ -1,6 +1,43 @@
1
1
  {
2
2
  "name": "@qilin-agent/storage-sqlite",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "description": "SQLite storage backend (kv facet) for the QiLin storage hub",
4
+ "version": "3.1.3",
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/kkutysllb/QiLin.git",
11
+ "directory": "packages/storage/storage-sqlite"
12
+ },
13
+ "engines": {
14
+ "node": "^22.19.0 || >=24.0.0"
15
+ },
16
+ "type": "module",
17
+ "main": "lib/index.js",
18
+ "types": "lib/types/index.d.ts",
19
+ "exports": {
20
+ ".": {
21
+ "types": "./lib/types/index.d.ts",
22
+ "default": "./lib/index.js"
23
+ },
24
+ "./src/*": "./src/*",
25
+ "./package.json": "./package.json"
26
+ },
27
+ "files": [
28
+ "lib/index.js",
29
+ "lib/types/**/*.d.ts"
30
+ ],
31
+ "license": "MIT",
32
+ "peerDependencies": {
33
+ "@qilin-agent/storage": "3.1.3",
34
+ "@qilin-agent/kylin": "~4.0.3"
35
+ },
36
+ "dependencies": {
37
+ "@qilin-agent/schemastery": "~3.18.3"
38
+ },
39
+ "devDependencies": {
40
+ "@qilin-agent/storage": "3.1.3",
41
+ "@qilin-agent/kylin": "~4.0.3"
42
+ }
6
43
  }