@qilin-agent/storage-sqlite 0.0.0-stage → 3.1.4
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 +21 -0
- package/README.i18n.yaml +64 -0
- package/README.md +140 -2
- package/README.zh.md +141 -0
- package/lib/index.js +308 -0
- package/lib/types/index.d.ts +71 -0
- package/lib/types/schema.d.ts +43 -0
- package/lib/types/unit.d.ts +47 -0
- package/package.json +40 -3
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.
|
package/README.i18n.yaml
ADDED
|
@@ -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-agent-storage-sqlite:
|
|
9
|
+
en: 1b6cb59e3f5bc830
|
|
10
|
+
zh: 693607e34d49324b
|
|
11
|
+
/qilin-agent-storage-sqlite/summary:
|
|
12
|
+
en: 8e38efc1d77eca8b
|
|
13
|
+
zh: cca2fec8e7ff8c2b
|
|
14
|
+
/qilin-agent-storage-sqlite/table-of-contents:
|
|
15
|
+
en: d152484eb41ac6b4
|
|
16
|
+
zh: 09388d293f9be9cb
|
|
17
|
+
/qilin-agent-storage-sqlite/use-this-package:
|
|
18
|
+
en: 98de508e10f22c1e
|
|
19
|
+
zh: 1e7d0cadc10cba8d
|
|
20
|
+
/qilin-agent-storage-sqlite/use-this-package/when-to-choose-it:
|
|
21
|
+
en: 8e1ba279af55e197
|
|
22
|
+
zh: 7dfad7470534de6c
|
|
23
|
+
/qilin-agent-storage-sqlite/use-this-package/configuration:
|
|
24
|
+
en: 3db7ea6a853e9355
|
|
25
|
+
zh: 665f796cf76be85a
|
|
26
|
+
/qilin-agent-storage-sqlite/use-this-package/observable-behavior:
|
|
27
|
+
en: b260d7bdf7971f9d
|
|
28
|
+
zh: 22dd2f633f507545
|
|
29
|
+
/qilin-agent-storage-sqlite/understand-the-implementation:
|
|
30
|
+
en: 6867b52cbb94e572
|
|
31
|
+
zh: 187d5d61980c8fe7
|
|
32
|
+
/qilin-agent-storage-sqlite/understand-the-implementation/design-concept:
|
|
33
|
+
en: 54ee8d9d7746e82d
|
|
34
|
+
zh: 2cc9f29ebcc29adc
|
|
35
|
+
/qilin-agent-storage-sqlite/understand-the-implementation/open-sequence:
|
|
36
|
+
en: 50d85e8d8e8b5bc1
|
|
37
|
+
zh: 2a7067bd7fb47b35
|
|
38
|
+
/qilin-agent-storage-sqlite/understand-the-implementation/source-map:
|
|
39
|
+
en: 79780e581c765030
|
|
40
|
+
zh: fa2bb0eaf915aab6
|
|
41
|
+
/qilin-agent-storage-sqlite/further-exploration:
|
|
42
|
+
en: 26308518b12a7833
|
|
43
|
+
zh: 3cb9e88930a07d8f
|
|
44
|
+
/qilin-agent-storage-sqlite/model-experience:
|
|
45
|
+
en: 215e7ba838619b7b
|
|
46
|
+
zh: a311da3843709f90
|
|
47
|
+
/qilin-agent-storage-sqlite/model-experience/stored-domain-records:
|
|
48
|
+
en: c5d5ffaf6b114f3e
|
|
49
|
+
zh: 97db23b0b14ff1c0
|
|
50
|
+
/qilin-agent-storage-sqlite/model-experience/stored-domain-records/what-the-model-sees:
|
|
51
|
+
en: d0798e9e30583b55
|
|
52
|
+
zh: 968f7f595b4bf1ff
|
|
53
|
+
/qilin-agent-storage-sqlite/model-experience/stored-domain-records/token-effect:
|
|
54
|
+
en: 592ed887c69e5c46
|
|
55
|
+
zh: cb9be9de6e38db55
|
|
56
|
+
/qilin-agent-storage-sqlite/model-experience/stored-domain-records/kv-cache-effect:
|
|
57
|
+
en: c13c59d13a5f1651
|
|
58
|
+
zh: 5aab838ae3ff5324
|
|
59
|
+
/qilin-agent-storage-sqlite/known-limitations-and-deferred-work:
|
|
60
|
+
en: c24fe7a01bc44ed3
|
|
61
|
+
zh: 69638d0692bdb637
|
|
62
|
+
/qilin-agent-storage-sqlite/known-limitations-and-deferred-work/dev-note:
|
|
63
|
+
en: e67f633dc6fe7773
|
|
64
|
+
zh: 3bb0c20c93f16f98
|
package/README.md
CHANGED
|
@@ -1,3 +1,141 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
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
|
-
"
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"description": "SQLite storage backend (kv facet) for the QiLin storage hub",
|
|
4
|
+
"version": "3.1.4",
|
|
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.4",
|
|
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.4",
|
|
41
|
+
"@qilin-agent/kylin": "~4.0.3"
|
|
42
|
+
}
|
|
6
43
|
}
|