@starkeep/storage-sqlite 0.4.0 → 0.5.0

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/dist/index.d.cts CHANGED
@@ -1,13 +1,50 @@
1
- export { S as SqliteDatabaseAdapter, a as SqliteDatabaseAdapterOptions, b as SqliteDriver } from './adapter-EloqOiMg.cjs';
1
+ export { S as SqliteDatabaseAdapter, a as SqliteDatabaseAdapterOptions, b as SqliteDriver } from './adapter-DoVOV6K-.cjs';
2
2
  import { Kysely } from 'kysely';
3
- import { RawDatabase } from '@starkeep/storage-adapter';
4
- import { AppSyncableNamespaceStore, AppSyncableNamespace, AppSyncableTableInfo, AppSyncableApplier, ScanCapableApplier, AppSyncableRowEntry, ScanSinceOptions, ScanSincePage } from '@starkeep/shared-space-api';
3
+ import { RawDatabase, DigestBucket, ParsedQuery, BuildOptions, ParsedQueryResult } from '@starkeep/storage-adapter';
4
+ import { AppSyncableNamespaceStore, AppSyncableNamespace, AppSyncableTableInfo, AppSyncableApplier, ScanCapableApplier, AppSyncableRowEntry, ScanSincePage } from '@starkeep/shared-space-api';
5
5
  export { AppSyncableNamespace, AppSyncableTableInfo } from '@starkeep/shared-space-api';
6
6
  import { HLCTimestamp } from '@starkeep/protocol-primitives';
7
7
 
8
8
  type DB = Record<string, Record<string, unknown>>;
9
9
  declare const compiler: Kysely<DB>;
10
10
 
11
+ /**
12
+ * Local sqlite schema bootstrap.
13
+ *
14
+ * Layout follows desired-state-roles-and-permissions.md "DSQL DDL ... Local
15
+ * SQLite asymmetry" section: prefix-named tables in one file instead of
16
+ * separate schemas. Only tables that something in phase 1 actually reads or
17
+ * writes are created here — promotion, metadata enrichment, and the janitor
18
+ * land as separate workstreams with their own DDL.
19
+ *
20
+ * - shared_records — all shared data, all types (file-backed only)
21
+ * - shared_record_<category>_metadata — per-category metadata rows (typed columns)
22
+ * - shared_record_labels — cross-app assertions about shared records
23
+ * - shared_access_grants — per-app, per-type permissions
24
+ * - shared_app_label_keys — manifest-declared label keys, per app
25
+ * - shared_app_registry — installed apps + HMAC secrets
26
+ * - shared_app_install_steps — idempotent install/uninstall ledger
27
+ *
28
+ * No migration system: this is a fresh-start schema. The user removes
29
+ * ~/.starkeep/data.db (or the local-data-server's STARKEEP_DIR is fresh)
30
+ * before this code runs.
31
+ */
32
+ /**
33
+ * Connection settings the query grammar's portability depends on.
34
+ *
35
+ * Separate from the schema DDL and exported because a connection can be opened
36
+ * without the full local schema — the conformance harness creates one table and
37
+ * nothing else — and a setting that the real server has and the conformance
38
+ * suite does not is a setting whose divergence the suite cannot catch.
39
+ *
40
+ * `case_sensitive_like` is the whole list today. SQLite's LIKE folds ASCII case
41
+ * by default and Postgres's does not, so `like: "photo%"` would otherwise match
42
+ * `PHOTO123` locally and not in the cloud. DSQL uses the `C` collation only, so
43
+ * with the fold turned off the two agree byte for byte. Turning it off also
44
+ * lets SQLite use a btree index for an anchored pattern, which the fold rules
45
+ * out.
46
+ */
47
+ declare function applyConnectionPragmas(db: RawDatabase): void;
11
48
  declare function initializeLocalSchema(db: RawDatabase): void;
12
49
 
13
50
  declare function appSyncableTableName(appId: string, tableName: string): string;
@@ -46,18 +83,132 @@ declare class SqliteAppSyncableApplier implements AppSyncableApplier, ScanCapabl
46
83
  private applyInsert;
47
84
  private applyUpdate;
48
85
  private applyDelete;
49
- /** See `ScanCapableApplier.getNodeWatermarks`. Missing table → `{}`. */
86
+ /**
87
+ * Whether this table exists in *this* database.
88
+ *
89
+ * Asked before the digest rather than inferred from a failed read, because
90
+ * those are two different answers and only one of them is `[]`. An app that
91
+ * is not installed here genuinely holds nothing; a table that is locked,
92
+ * corrupt or unreadable holds an unknown number of rows, and reporting zero
93
+ * for it is the loudest possible false alarm — every bucket in it reads as a
94
+ * hole, in whichever direction the comparison runs.
95
+ *
96
+ * `sqlite_master` is the cheapest question that separates them, and asking it
97
+ * cannot itself fail for a reason worth swallowing: a database whose schema
98
+ * table will not read is not one whose app tables are merely absent.
99
+ */
100
+ private tableExists;
101
+ /**
102
+ * See `ScanCapableApplier.bucketDigest`. Missing table → `[]`; a table that
103
+ * exists and will not read **throws**, so the caller's `supported: false`
104
+ * path can do its job.
105
+ *
106
+ * This used to be `try { … } catch { return [] }`, which is the same mistake
107
+ * `scanSince` made: `[]` is the wire value for "this table holds nothing", not
108
+ * for "I could not count it". It made both engine-side "could not count ⇒
109
+ * supported: false" guards unreachable on every production path, because no
110
+ * real applier ever threw.
111
+ */
112
+ bucketDigest(appId: string, table: string, prefixLength?: number): Promise<DigestBucket[]>;
113
+ /**
114
+ * See `ScanCapableApplier.getNodeWatermarks`. Missing table → `{}`; a table
115
+ * that exists and will not read **throws**.
116
+ *
117
+ * The distinction matters more here than the `{}` return suggests, because
118
+ * `scanSince` plans its authors from this map: an unreadable table that
119
+ * answered `{}` produced no scans, and the scan then reported "nothing owed,
120
+ * every author complete" — the exact silent-loss shape `scanSince`'s own catch
121
+ * was written to prevent, reached one frame earlier.
122
+ */
50
123
  getNodeWatermarks(appId: string, table: string): Promise<Record<string, HLCTimestamp>>;
51
124
  /**
52
- * Pull-side synthesis: return rows updated after `sinceHlcStr` (or `cursor`
53
- * if higher) in HLC order, paginated. `updated_at` is a serialized HLC
54
- * whose lexicographic order matches HLC order (fixed-width hex), and each
55
- * row's HLC is unique per node, so it doubles as the cursor — no separate
56
- * tiebreaker column is needed.
125
+ * Pull-side synthesis: rows the peer hasn't seen, per author, seeking the
126
+ * `(node_id, updated_at)` index rather than reading the table and filtering.
127
+ * See `ScanCapableApplier.scanSince` for the contract and
128
+ * `storage-adapter/src/database/since-queries.ts` for why it is a loop.
129
+ */
130
+ scanSince(appId: string, table: string, peerWatermarks: Record<string, HLCTimestamp>, limit: number): Promise<ScanSincePage>;
131
+ /**
132
+ * Run a parsed query. The read half of the app-data plane.
133
+ *
134
+ * Compiled by the shared builder rather than here, so the SQL this emits and
135
+ * the SQL the DSQL applier emits are one piece of code — the two hand-written
136
+ * read grammars this replaces had already drifted on their limit defaults
137
+ * alone.
57
138
  */
58
- scanSince(appId: string, table: string, sinceHlcStr: string, options?: ScanSinceOptions): Promise<ScanSincePage>;
59
- /** Support read path from the factory's queryRows. */
60
- queryRows(appId: string, table: string, where?: Record<string, unknown>): Record<string, unknown>[];
139
+ runQuery(appId: string, table: string, query: ParsedQuery, options?: BuildOptions): Promise<ParsedQueryResult>;
140
+ /** The names of a declared table's `boolean` columns, or null when it has none. */
141
+ private booleanColumnsOf;
142
+ /** Bind and run a compiled SELECT, adapting values SQLite cannot bind. */
143
+ private selectRows;
144
+ }
145
+
146
+ /**
147
+ * Which user a node's library belongs to, and the database half of binding it.
148
+ *
149
+ * One node serves one cloud user. Every object key carries its owner's segment
150
+ * (`shared/<userId>/...`, `apps/<appId>/<userId>/syncable/...`), and a library
151
+ * no cloud has bound yet writes under `LOCAL_USER_SEGMENT`. The first time the
152
+ * node signs in, the ID token's `sub` names the user, and binding renames the
153
+ * `local` segment to that user's id before the first sync:
154
+ * on disk, which each host does its own way, and in every stored key, which
155
+ * this file does for every host. After that, a cloud that names a different
156
+ * user stops sync rather than mixing two users' data.
157
+ *
158
+ * ## The order a host binds in
159
+ *
160
+ * 1. {@link checkLibraryBindable}, which refuses a library bound elsewhere.
161
+ * 2. Move the files under `local` to the user's segment.
162
+ * 3. {@link commitLibraryBinding}, which rewrites the stored keys and stores
163
+ * the user last, in one transaction.
164
+ *
165
+ * A crash part-way leaves the library unbound, so the next start runs the
166
+ * pass again. Every step is idempotent: a file move merges into one already
167
+ * made, and the key rewrites match only keys that still carry `local`.
168
+ *
169
+ * ## The sweep
170
+ *
171
+ * The pass also runs for a library already bound to the same user. A write
172
+ * that built its key under `local` before the pass and landed after it is
173
+ * moved and rewritten by the next pass.
174
+ *
175
+ * See `~/projects/starkeep/plan-multi-user-roles-2026-10-16.md`, step 4.9.
176
+ */
177
+
178
+ /** The user this library is bound to, or null while unbound. */
179
+ declare function boundUserId(db: RawDatabase): string | null;
180
+ /** The segment this library writes keys under: its bound user, or `local`. */
181
+ declare function libraryUserSegment(db: RawDatabase): string;
182
+ /** A column that can hold a `local` key. */
183
+ interface LibraryKeyColumn {
184
+ readonly table: string;
185
+ readonly column: string;
186
+ /** Whether the column is the table's primary key, so a rewrite can collide. */
187
+ readonly primaryKey: boolean;
188
+ }
189
+ /**
190
+ * The key columns every SQLite node has: records, availability, the resident
191
+ * set, and each app's file index, which stores the full key as its row id.
192
+ * Only the tables this database holds.
193
+ */
194
+ declare function libraryKeyColumns(db: RawDatabase): LibraryKeyColumn[];
195
+ /** The cloud names a different user than the one this library belongs to. */
196
+ declare class LibraryBoundElsewhereError extends Error {
197
+ readonly boundTo: string;
198
+ readonly cloudSays: string;
199
+ constructor(boundTo: string, cloudSays: string);
61
200
  }
201
+ /**
202
+ * Refuse to bind the library to `userId` when it cannot be: the id is not a
203
+ * user segment, or the library belongs to someone else. Runs before a host
204
+ * moves any file.
205
+ */
206
+ declare function checkLibraryBindable(db: RawDatabase, userId: string): void;
207
+ /**
208
+ * Rewrite every stored key from `local` to `userId`, then store the user, in
209
+ * one transaction. A host passes the key columns of its own tables in
210
+ * `extraKeyColumns`. Returns how many keys changed.
211
+ */
212
+ declare function commitLibraryBinding(db: RawDatabase, userId: string, extraKeyColumns?: readonly LibraryKeyColumn[]): number;
62
213
 
63
- export { SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, appSyncableTableName, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, listAppSyncableNamespaces, compiler as sqliteCompiler, upsertAppSyncableNamespace };
214
+ export { LibraryBoundElsewhereError, type LibraryKeyColumn, SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, appSyncableTableName, applyConnectionPragmas, boundUserId, checkLibraryBindable, commitLibraryBinding, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, libraryKeyColumns, libraryUserSegment, listAppSyncableNamespaces, compiler as sqliteCompiler, upsertAppSyncableNamespace };
package/dist/index.d.ts CHANGED
@@ -1,13 +1,50 @@
1
- export { S as SqliteDatabaseAdapter, a as SqliteDatabaseAdapterOptions, b as SqliteDriver } from './adapter-EloqOiMg.js';
1
+ export { S as SqliteDatabaseAdapter, a as SqliteDatabaseAdapterOptions, b as SqliteDriver } from './adapter-DoVOV6K-.js';
2
2
  import { Kysely } from 'kysely';
3
- import { RawDatabase } from '@starkeep/storage-adapter';
4
- import { AppSyncableNamespaceStore, AppSyncableNamespace, AppSyncableTableInfo, AppSyncableApplier, ScanCapableApplier, AppSyncableRowEntry, ScanSinceOptions, ScanSincePage } from '@starkeep/shared-space-api';
3
+ import { RawDatabase, DigestBucket, ParsedQuery, BuildOptions, ParsedQueryResult } from '@starkeep/storage-adapter';
4
+ import { AppSyncableNamespaceStore, AppSyncableNamespace, AppSyncableTableInfo, AppSyncableApplier, ScanCapableApplier, AppSyncableRowEntry, ScanSincePage } from '@starkeep/shared-space-api';
5
5
  export { AppSyncableNamespace, AppSyncableTableInfo } from '@starkeep/shared-space-api';
6
6
  import { HLCTimestamp } from '@starkeep/protocol-primitives';
7
7
 
8
8
  type DB = Record<string, Record<string, unknown>>;
9
9
  declare const compiler: Kysely<DB>;
10
10
 
11
+ /**
12
+ * Local sqlite schema bootstrap.
13
+ *
14
+ * Layout follows desired-state-roles-and-permissions.md "DSQL DDL ... Local
15
+ * SQLite asymmetry" section: prefix-named tables in one file instead of
16
+ * separate schemas. Only tables that something in phase 1 actually reads or
17
+ * writes are created here — promotion, metadata enrichment, and the janitor
18
+ * land as separate workstreams with their own DDL.
19
+ *
20
+ * - shared_records — all shared data, all types (file-backed only)
21
+ * - shared_record_<category>_metadata — per-category metadata rows (typed columns)
22
+ * - shared_record_labels — cross-app assertions about shared records
23
+ * - shared_access_grants — per-app, per-type permissions
24
+ * - shared_app_label_keys — manifest-declared label keys, per app
25
+ * - shared_app_registry — installed apps + HMAC secrets
26
+ * - shared_app_install_steps — idempotent install/uninstall ledger
27
+ *
28
+ * No migration system: this is a fresh-start schema. The user removes
29
+ * ~/.starkeep/data.db (or the local-data-server's STARKEEP_DIR is fresh)
30
+ * before this code runs.
31
+ */
32
+ /**
33
+ * Connection settings the query grammar's portability depends on.
34
+ *
35
+ * Separate from the schema DDL and exported because a connection can be opened
36
+ * without the full local schema — the conformance harness creates one table and
37
+ * nothing else — and a setting that the real server has and the conformance
38
+ * suite does not is a setting whose divergence the suite cannot catch.
39
+ *
40
+ * `case_sensitive_like` is the whole list today. SQLite's LIKE folds ASCII case
41
+ * by default and Postgres's does not, so `like: "photo%"` would otherwise match
42
+ * `PHOTO123` locally and not in the cloud. DSQL uses the `C` collation only, so
43
+ * with the fold turned off the two agree byte for byte. Turning it off also
44
+ * lets SQLite use a btree index for an anchored pattern, which the fold rules
45
+ * out.
46
+ */
47
+ declare function applyConnectionPragmas(db: RawDatabase): void;
11
48
  declare function initializeLocalSchema(db: RawDatabase): void;
12
49
 
13
50
  declare function appSyncableTableName(appId: string, tableName: string): string;
@@ -46,18 +83,132 @@ declare class SqliteAppSyncableApplier implements AppSyncableApplier, ScanCapabl
46
83
  private applyInsert;
47
84
  private applyUpdate;
48
85
  private applyDelete;
49
- /** See `ScanCapableApplier.getNodeWatermarks`. Missing table → `{}`. */
86
+ /**
87
+ * Whether this table exists in *this* database.
88
+ *
89
+ * Asked before the digest rather than inferred from a failed read, because
90
+ * those are two different answers and only one of them is `[]`. An app that
91
+ * is not installed here genuinely holds nothing; a table that is locked,
92
+ * corrupt or unreadable holds an unknown number of rows, and reporting zero
93
+ * for it is the loudest possible false alarm — every bucket in it reads as a
94
+ * hole, in whichever direction the comparison runs.
95
+ *
96
+ * `sqlite_master` is the cheapest question that separates them, and asking it
97
+ * cannot itself fail for a reason worth swallowing: a database whose schema
98
+ * table will not read is not one whose app tables are merely absent.
99
+ */
100
+ private tableExists;
101
+ /**
102
+ * See `ScanCapableApplier.bucketDigest`. Missing table → `[]`; a table that
103
+ * exists and will not read **throws**, so the caller's `supported: false`
104
+ * path can do its job.
105
+ *
106
+ * This used to be `try { … } catch { return [] }`, which is the same mistake
107
+ * `scanSince` made: `[]` is the wire value for "this table holds nothing", not
108
+ * for "I could not count it". It made both engine-side "could not count ⇒
109
+ * supported: false" guards unreachable on every production path, because no
110
+ * real applier ever threw.
111
+ */
112
+ bucketDigest(appId: string, table: string, prefixLength?: number): Promise<DigestBucket[]>;
113
+ /**
114
+ * See `ScanCapableApplier.getNodeWatermarks`. Missing table → `{}`; a table
115
+ * that exists and will not read **throws**.
116
+ *
117
+ * The distinction matters more here than the `{}` return suggests, because
118
+ * `scanSince` plans its authors from this map: an unreadable table that
119
+ * answered `{}` produced no scans, and the scan then reported "nothing owed,
120
+ * every author complete" — the exact silent-loss shape `scanSince`'s own catch
121
+ * was written to prevent, reached one frame earlier.
122
+ */
50
123
  getNodeWatermarks(appId: string, table: string): Promise<Record<string, HLCTimestamp>>;
51
124
  /**
52
- * Pull-side synthesis: return rows updated after `sinceHlcStr` (or `cursor`
53
- * if higher) in HLC order, paginated. `updated_at` is a serialized HLC
54
- * whose lexicographic order matches HLC order (fixed-width hex), and each
55
- * row's HLC is unique per node, so it doubles as the cursor — no separate
56
- * tiebreaker column is needed.
125
+ * Pull-side synthesis: rows the peer hasn't seen, per author, seeking the
126
+ * `(node_id, updated_at)` index rather than reading the table and filtering.
127
+ * See `ScanCapableApplier.scanSince` for the contract and
128
+ * `storage-adapter/src/database/since-queries.ts` for why it is a loop.
129
+ */
130
+ scanSince(appId: string, table: string, peerWatermarks: Record<string, HLCTimestamp>, limit: number): Promise<ScanSincePage>;
131
+ /**
132
+ * Run a parsed query. The read half of the app-data plane.
133
+ *
134
+ * Compiled by the shared builder rather than here, so the SQL this emits and
135
+ * the SQL the DSQL applier emits are one piece of code — the two hand-written
136
+ * read grammars this replaces had already drifted on their limit defaults
137
+ * alone.
57
138
  */
58
- scanSince(appId: string, table: string, sinceHlcStr: string, options?: ScanSinceOptions): Promise<ScanSincePage>;
59
- /** Support read path from the factory's queryRows. */
60
- queryRows(appId: string, table: string, where?: Record<string, unknown>): Record<string, unknown>[];
139
+ runQuery(appId: string, table: string, query: ParsedQuery, options?: BuildOptions): Promise<ParsedQueryResult>;
140
+ /** The names of a declared table's `boolean` columns, or null when it has none. */
141
+ private booleanColumnsOf;
142
+ /** Bind and run a compiled SELECT, adapting values SQLite cannot bind. */
143
+ private selectRows;
144
+ }
145
+
146
+ /**
147
+ * Which user a node's library belongs to, and the database half of binding it.
148
+ *
149
+ * One node serves one cloud user. Every object key carries its owner's segment
150
+ * (`shared/<userId>/...`, `apps/<appId>/<userId>/syncable/...`), and a library
151
+ * no cloud has bound yet writes under `LOCAL_USER_SEGMENT`. The first time the
152
+ * node signs in, the ID token's `sub` names the user, and binding renames the
153
+ * `local` segment to that user's id before the first sync:
154
+ * on disk, which each host does its own way, and in every stored key, which
155
+ * this file does for every host. After that, a cloud that names a different
156
+ * user stops sync rather than mixing two users' data.
157
+ *
158
+ * ## The order a host binds in
159
+ *
160
+ * 1. {@link checkLibraryBindable}, which refuses a library bound elsewhere.
161
+ * 2. Move the files under `local` to the user's segment.
162
+ * 3. {@link commitLibraryBinding}, which rewrites the stored keys and stores
163
+ * the user last, in one transaction.
164
+ *
165
+ * A crash part-way leaves the library unbound, so the next start runs the
166
+ * pass again. Every step is idempotent: a file move merges into one already
167
+ * made, and the key rewrites match only keys that still carry `local`.
168
+ *
169
+ * ## The sweep
170
+ *
171
+ * The pass also runs for a library already bound to the same user. A write
172
+ * that built its key under `local` before the pass and landed after it is
173
+ * moved and rewritten by the next pass.
174
+ *
175
+ * See `~/projects/starkeep/plan-multi-user-roles-2026-10-16.md`, step 4.9.
176
+ */
177
+
178
+ /** The user this library is bound to, or null while unbound. */
179
+ declare function boundUserId(db: RawDatabase): string | null;
180
+ /** The segment this library writes keys under: its bound user, or `local`. */
181
+ declare function libraryUserSegment(db: RawDatabase): string;
182
+ /** A column that can hold a `local` key. */
183
+ interface LibraryKeyColumn {
184
+ readonly table: string;
185
+ readonly column: string;
186
+ /** Whether the column is the table's primary key, so a rewrite can collide. */
187
+ readonly primaryKey: boolean;
188
+ }
189
+ /**
190
+ * The key columns every SQLite node has: records, availability, the resident
191
+ * set, and each app's file index, which stores the full key as its row id.
192
+ * Only the tables this database holds.
193
+ */
194
+ declare function libraryKeyColumns(db: RawDatabase): LibraryKeyColumn[];
195
+ /** The cloud names a different user than the one this library belongs to. */
196
+ declare class LibraryBoundElsewhereError extends Error {
197
+ readonly boundTo: string;
198
+ readonly cloudSays: string;
199
+ constructor(boundTo: string, cloudSays: string);
61
200
  }
201
+ /**
202
+ * Refuse to bind the library to `userId` when it cannot be: the id is not a
203
+ * user segment, or the library belongs to someone else. Runs before a host
204
+ * moves any file.
205
+ */
206
+ declare function checkLibraryBindable(db: RawDatabase, userId: string): void;
207
+ /**
208
+ * Rewrite every stored key from `local` to `userId`, then store the user, in
209
+ * one transaction. A host passes the key columns of its own tables in
210
+ * `extraKeyColumns`. Returns how many keys changed.
211
+ */
212
+ declare function commitLibraryBinding(db: RawDatabase, userId: string, extraKeyColumns?: readonly LibraryKeyColumn[]): number;
62
213
 
63
- export { SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, appSyncableTableName, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, listAppSyncableNamespaces, compiler as sqliteCompiler, upsertAppSyncableNamespace };
214
+ export { LibraryBoundElsewhereError, type LibraryKeyColumn, SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, appSyncableTableName, applyConnectionPragmas, boundUserId, checkLibraryBindable, commitLibraryBinding, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, libraryKeyColumns, libraryUserSegment, listAppSyncableNamespaces, compiler as sqliteCompiler, upsertAppSyncableNamespace };