@starkeep/storage-sqlite 0.3.1 → 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/README.md +4 -4
- package/dist/adapter-DoVOV6K-.d.cts +126 -0
- package/dist/adapter-DoVOV6K-.d.ts +126 -0
- package/dist/index.cjs +617 -214
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +172 -71
- package/dist/index.d.ts +172 -71
- package/dist/index.js +645 -193
- package/dist/index.js.map +1 -1
- package/dist/node-entry.cjs +45 -0
- package/dist/node-entry.cjs.map +1 -0
- package/dist/node-entry.d.cts +32 -0
- package/dist/node-entry.d.ts +32 -0
- package/dist/node-entry.js +18 -0
- package/dist/node-entry.js.map +1 -0
- package/package.json +10 -5
package/dist/index.d.cts
CHANGED
|
@@ -1,70 +1,57 @@
|
|
|
1
|
-
|
|
2
|
-
import { DataRecord, StarkeepId, HLCTimestamp, MetadataRow, RecordLabel } from '@starkeep/protocol-primitives';
|
|
3
|
-
import { DatabaseAdapter, Query, QueryResult, BatchOperation, Transaction, LabelUpsert, LabelRetraction, LabelValueReplacement, FindByLabelQuery, FindByLabelResult } from '@starkeep/storage-adapter';
|
|
1
|
+
export { S as SqliteDatabaseAdapter, a as SqliteDatabaseAdapterOptions, b as SqliteDriver } from './adapter-DoVOV6K-.cjs';
|
|
4
2
|
import { Kysely } from 'kysely';
|
|
5
|
-
import {
|
|
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';
|
|
6
5
|
export { AppSyncableNamespace, AppSyncableTableInfo } from '@starkeep/shared-space-api';
|
|
7
|
-
|
|
8
|
-
interface SqliteDatabaseAdapterOptions {
|
|
9
|
-
path: string | ":memory:";
|
|
10
|
-
}
|
|
11
|
-
declare class SqliteDatabaseAdapter implements DatabaseAdapter {
|
|
12
|
-
private database;
|
|
13
|
-
private readonly options;
|
|
14
|
-
constructor(options: SqliteDatabaseAdapterOptions);
|
|
15
|
-
init(): Promise<void>;
|
|
16
|
-
close(): Promise<void>;
|
|
17
|
-
healthCheck(): Promise<boolean>;
|
|
18
|
-
private getDatabase;
|
|
19
|
-
/**
|
|
20
|
-
* Returns the raw SQLite connection so sibling subsystems (e.g. the sync
|
|
21
|
-
* engine's change log + state store) can create side tables in the same
|
|
22
|
-
* database file. Callers must only use this after `init()`.
|
|
23
|
-
*/
|
|
24
|
-
getRawDatabase(): DatabaseSync;
|
|
25
|
-
private runStmt;
|
|
26
|
-
private getRow;
|
|
27
|
-
private allRows;
|
|
28
|
-
put(record: DataRecord): Promise<void>;
|
|
29
|
-
get(id: StarkeepId): Promise<DataRecord | null>;
|
|
30
|
-
delete(id: StarkeepId, hlc: HLCTimestamp): Promise<void>;
|
|
31
|
-
getNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
|
|
32
|
-
query(query: Query): Promise<QueryResult>;
|
|
33
|
-
batch(operations: BatchOperation[]): Promise<void>;
|
|
34
|
-
transaction<T>(callback: (transaction: Transaction) => Promise<T>): Promise<T>;
|
|
35
|
-
putMetadata(typeId: string, row: MetadataRow): Promise<void>;
|
|
36
|
-
getMetadata(typeId: string, recordId: StarkeepId): Promise<MetadataRow | null>;
|
|
37
|
-
getMetadataByIds(typeId: string, recordIds: StarkeepId[]): Promise<Map<StarkeepId, MetadataRow>>;
|
|
38
|
-
deleteMetadata(typeId: string, recordId: StarkeepId): Promise<void>;
|
|
39
|
-
upsertLabels(labels: LabelUpsert[]): Promise<void>;
|
|
40
|
-
retractLabels(retractions: LabelRetraction[]): Promise<void>;
|
|
41
|
-
replaceLabelValues(replacements: LabelValueReplacement[]): Promise<void>;
|
|
42
|
-
getLabelsByRecordIds(recordIds: StarkeepId[]): Promise<Map<StarkeepId, RecordLabel[]>>;
|
|
43
|
-
findByLabel(query: FindByLabelQuery): Promise<FindByLabelResult>;
|
|
44
|
-
putLabel(label: RecordLabel): Promise<void>;
|
|
45
|
-
getLabel(recordId: StarkeepId, appId: string, key: string, value: string): Promise<RecordLabel | null>;
|
|
46
|
-
queryLabels(query: {
|
|
47
|
-
limit?: number;
|
|
48
|
-
cursor?: string;
|
|
49
|
-
}): Promise<{
|
|
50
|
-
labels: RecordLabel[];
|
|
51
|
-
nextCursor: string | null;
|
|
52
|
-
hasMore: boolean;
|
|
53
|
-
}>;
|
|
54
|
-
getLabelNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
|
|
55
|
-
tombstoneLabelsForRecord(recordId: StarkeepId, hlc: HLCTimestamp): Promise<void>;
|
|
56
|
-
}
|
|
6
|
+
import { HLCTimestamp } from '@starkeep/protocol-primitives';
|
|
57
7
|
|
|
58
8
|
type DB = Record<string, Record<string, unknown>>;
|
|
59
9
|
declare const compiler: Kysely<DB>;
|
|
60
10
|
|
|
61
|
-
|
|
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;
|
|
48
|
+
declare function initializeLocalSchema(db: RawDatabase): void;
|
|
62
49
|
|
|
63
50
|
declare function appSyncableTableName(appId: string, tableName: string): string;
|
|
64
|
-
declare function upsertAppSyncableNamespace(db:
|
|
65
|
-
declare function deleteAppSyncableNamespace(db:
|
|
66
|
-
declare function getAppSyncableNamespace(db:
|
|
67
|
-
declare function listAppSyncableNamespaces(db:
|
|
51
|
+
declare function upsertAppSyncableNamespace(db: RawDatabase, appId: string, tables: AppSyncableTableInfo[], filesEnabled: boolean): void;
|
|
52
|
+
declare function deleteAppSyncableNamespace(db: RawDatabase, appId: string): void;
|
|
53
|
+
declare function getAppSyncableNamespace(db: RawDatabase, appId: string): AppSyncableNamespace | null;
|
|
54
|
+
declare function listAppSyncableNamespaces(db: RawDatabase): AppSyncableNamespace[];
|
|
68
55
|
/**
|
|
69
56
|
* Object-oriented wrapper over the free functions above — implements the
|
|
70
57
|
* `AppSyncableNamespaceStore` interface required by `createAppSpecificFactory`
|
|
@@ -72,7 +59,7 @@ declare function listAppSyncableNamespaces(db: DatabaseSync): AppSyncableNamespa
|
|
|
72
59
|
*/
|
|
73
60
|
declare class SqliteAppSyncableNamespaceStore implements AppSyncableNamespaceStore {
|
|
74
61
|
private readonly db;
|
|
75
|
-
constructor(db:
|
|
62
|
+
constructor(db: RawDatabase);
|
|
76
63
|
get(appId: string): AppSyncableNamespace | null;
|
|
77
64
|
list(): AppSyncableNamespace[];
|
|
78
65
|
}
|
|
@@ -91,23 +78,137 @@ declare class SqliteAppSyncableNamespaceStore implements AppSyncableNamespaceSto
|
|
|
91
78
|
declare class SqliteAppSyncableApplier implements AppSyncableApplier, ScanCapableApplier {
|
|
92
79
|
private readonly db;
|
|
93
80
|
private readonly namespace;
|
|
94
|
-
constructor(db:
|
|
81
|
+
constructor(db: RawDatabase, namespace: AppSyncableNamespaceStore);
|
|
95
82
|
apply(entry: AppSyncableRowEntry): void;
|
|
96
83
|
private applyInsert;
|
|
97
84
|
private applyUpdate;
|
|
98
85
|
private applyDelete;
|
|
99
|
-
/**
|
|
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
|
+
*/
|
|
100
123
|
getNodeWatermarks(appId: string, table: string): Promise<Record<string, HLCTimestamp>>;
|
|
101
124
|
/**
|
|
102
|
-
* Pull-side synthesis:
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
* 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.
|
|
107
129
|
*/
|
|
108
|
-
scanSince(appId: string, table: string,
|
|
109
|
-
/**
|
|
110
|
-
|
|
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.
|
|
138
|
+
*/
|
|
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);
|
|
111
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;
|
|
112
213
|
|
|
113
|
-
export { SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore,
|
|
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,70 +1,57 @@
|
|
|
1
|
-
|
|
2
|
-
import { DataRecord, StarkeepId, HLCTimestamp, MetadataRow, RecordLabel } from '@starkeep/protocol-primitives';
|
|
3
|
-
import { DatabaseAdapter, Query, QueryResult, BatchOperation, Transaction, LabelUpsert, LabelRetraction, LabelValueReplacement, FindByLabelQuery, FindByLabelResult } from '@starkeep/storage-adapter';
|
|
1
|
+
export { S as SqliteDatabaseAdapter, a as SqliteDatabaseAdapterOptions, b as SqliteDriver } from './adapter-DoVOV6K-.js';
|
|
4
2
|
import { Kysely } from 'kysely';
|
|
5
|
-
import {
|
|
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';
|
|
6
5
|
export { AppSyncableNamespace, AppSyncableTableInfo } from '@starkeep/shared-space-api';
|
|
7
|
-
|
|
8
|
-
interface SqliteDatabaseAdapterOptions {
|
|
9
|
-
path: string | ":memory:";
|
|
10
|
-
}
|
|
11
|
-
declare class SqliteDatabaseAdapter implements DatabaseAdapter {
|
|
12
|
-
private database;
|
|
13
|
-
private readonly options;
|
|
14
|
-
constructor(options: SqliteDatabaseAdapterOptions);
|
|
15
|
-
init(): Promise<void>;
|
|
16
|
-
close(): Promise<void>;
|
|
17
|
-
healthCheck(): Promise<boolean>;
|
|
18
|
-
private getDatabase;
|
|
19
|
-
/**
|
|
20
|
-
* Returns the raw SQLite connection so sibling subsystems (e.g. the sync
|
|
21
|
-
* engine's change log + state store) can create side tables in the same
|
|
22
|
-
* database file. Callers must only use this after `init()`.
|
|
23
|
-
*/
|
|
24
|
-
getRawDatabase(): DatabaseSync;
|
|
25
|
-
private runStmt;
|
|
26
|
-
private getRow;
|
|
27
|
-
private allRows;
|
|
28
|
-
put(record: DataRecord): Promise<void>;
|
|
29
|
-
get(id: StarkeepId): Promise<DataRecord | null>;
|
|
30
|
-
delete(id: StarkeepId, hlc: HLCTimestamp): Promise<void>;
|
|
31
|
-
getNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
|
|
32
|
-
query(query: Query): Promise<QueryResult>;
|
|
33
|
-
batch(operations: BatchOperation[]): Promise<void>;
|
|
34
|
-
transaction<T>(callback: (transaction: Transaction) => Promise<T>): Promise<T>;
|
|
35
|
-
putMetadata(typeId: string, row: MetadataRow): Promise<void>;
|
|
36
|
-
getMetadata(typeId: string, recordId: StarkeepId): Promise<MetadataRow | null>;
|
|
37
|
-
getMetadataByIds(typeId: string, recordIds: StarkeepId[]): Promise<Map<StarkeepId, MetadataRow>>;
|
|
38
|
-
deleteMetadata(typeId: string, recordId: StarkeepId): Promise<void>;
|
|
39
|
-
upsertLabels(labels: LabelUpsert[]): Promise<void>;
|
|
40
|
-
retractLabels(retractions: LabelRetraction[]): Promise<void>;
|
|
41
|
-
replaceLabelValues(replacements: LabelValueReplacement[]): Promise<void>;
|
|
42
|
-
getLabelsByRecordIds(recordIds: StarkeepId[]): Promise<Map<StarkeepId, RecordLabel[]>>;
|
|
43
|
-
findByLabel(query: FindByLabelQuery): Promise<FindByLabelResult>;
|
|
44
|
-
putLabel(label: RecordLabel): Promise<void>;
|
|
45
|
-
getLabel(recordId: StarkeepId, appId: string, key: string, value: string): Promise<RecordLabel | null>;
|
|
46
|
-
queryLabels(query: {
|
|
47
|
-
limit?: number;
|
|
48
|
-
cursor?: string;
|
|
49
|
-
}): Promise<{
|
|
50
|
-
labels: RecordLabel[];
|
|
51
|
-
nextCursor: string | null;
|
|
52
|
-
hasMore: boolean;
|
|
53
|
-
}>;
|
|
54
|
-
getLabelNodeWatermarks(): Promise<Record<string, HLCTimestamp>>;
|
|
55
|
-
tombstoneLabelsForRecord(recordId: StarkeepId, hlc: HLCTimestamp): Promise<void>;
|
|
56
|
-
}
|
|
6
|
+
import { HLCTimestamp } from '@starkeep/protocol-primitives';
|
|
57
7
|
|
|
58
8
|
type DB = Record<string, Record<string, unknown>>;
|
|
59
9
|
declare const compiler: Kysely<DB>;
|
|
60
10
|
|
|
61
|
-
|
|
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;
|
|
48
|
+
declare function initializeLocalSchema(db: RawDatabase): void;
|
|
62
49
|
|
|
63
50
|
declare function appSyncableTableName(appId: string, tableName: string): string;
|
|
64
|
-
declare function upsertAppSyncableNamespace(db:
|
|
65
|
-
declare function deleteAppSyncableNamespace(db:
|
|
66
|
-
declare function getAppSyncableNamespace(db:
|
|
67
|
-
declare function listAppSyncableNamespaces(db:
|
|
51
|
+
declare function upsertAppSyncableNamespace(db: RawDatabase, appId: string, tables: AppSyncableTableInfo[], filesEnabled: boolean): void;
|
|
52
|
+
declare function deleteAppSyncableNamespace(db: RawDatabase, appId: string): void;
|
|
53
|
+
declare function getAppSyncableNamespace(db: RawDatabase, appId: string): AppSyncableNamespace | null;
|
|
54
|
+
declare function listAppSyncableNamespaces(db: RawDatabase): AppSyncableNamespace[];
|
|
68
55
|
/**
|
|
69
56
|
* Object-oriented wrapper over the free functions above — implements the
|
|
70
57
|
* `AppSyncableNamespaceStore` interface required by `createAppSpecificFactory`
|
|
@@ -72,7 +59,7 @@ declare function listAppSyncableNamespaces(db: DatabaseSync): AppSyncableNamespa
|
|
|
72
59
|
*/
|
|
73
60
|
declare class SqliteAppSyncableNamespaceStore implements AppSyncableNamespaceStore {
|
|
74
61
|
private readonly db;
|
|
75
|
-
constructor(db:
|
|
62
|
+
constructor(db: RawDatabase);
|
|
76
63
|
get(appId: string): AppSyncableNamespace | null;
|
|
77
64
|
list(): AppSyncableNamespace[];
|
|
78
65
|
}
|
|
@@ -91,23 +78,137 @@ declare class SqliteAppSyncableNamespaceStore implements AppSyncableNamespaceSto
|
|
|
91
78
|
declare class SqliteAppSyncableApplier implements AppSyncableApplier, ScanCapableApplier {
|
|
92
79
|
private readonly db;
|
|
93
80
|
private readonly namespace;
|
|
94
|
-
constructor(db:
|
|
81
|
+
constructor(db: RawDatabase, namespace: AppSyncableNamespaceStore);
|
|
95
82
|
apply(entry: AppSyncableRowEntry): void;
|
|
96
83
|
private applyInsert;
|
|
97
84
|
private applyUpdate;
|
|
98
85
|
private applyDelete;
|
|
99
|
-
/**
|
|
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
|
+
*/
|
|
100
123
|
getNodeWatermarks(appId: string, table: string): Promise<Record<string, HLCTimestamp>>;
|
|
101
124
|
/**
|
|
102
|
-
* Pull-side synthesis:
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
* 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.
|
|
107
129
|
*/
|
|
108
|
-
scanSince(appId: string, table: string,
|
|
109
|
-
/**
|
|
110
|
-
|
|
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.
|
|
138
|
+
*/
|
|
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);
|
|
111
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;
|
|
112
213
|
|
|
113
|
-
export { SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore,
|
|
214
|
+
export { LibraryBoundElsewhereError, type LibraryKeyColumn, SqliteAppSyncableApplier, SqliteAppSyncableNamespaceStore, appSyncableTableName, applyConnectionPragmas, boundUserId, checkLibraryBindable, commitLibraryBinding, deleteAppSyncableNamespace, getAppSyncableNamespace, initializeLocalSchema, libraryKeyColumns, libraryUserSegment, listAppSyncableNamespaces, compiler as sqliteCompiler, upsertAppSyncableNamespace };
|