@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/dist/index.d.cts CHANGED
@@ -1,70 +1,57 @@
1
- import { DatabaseSync } from 'node:sqlite';
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 { 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';
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
- declare function initializeLocalSchema(db: DatabaseSync): void;
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: DatabaseSync, appId: string, tables: AppSyncableTableInfo[], filesEnabled: boolean): void;
65
- declare function deleteAppSyncableNamespace(db: DatabaseSync, appId: string): void;
66
- declare function getAppSyncableNamespace(db: DatabaseSync, appId: string): AppSyncableNamespace | null;
67
- declare function listAppSyncableNamespaces(db: DatabaseSync): AppSyncableNamespace[];
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: DatabaseSync);
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: DatabaseSync, namespace: AppSyncableNamespaceStore);
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
- /** 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
+ */
100
123
  getNodeWatermarks(appId: string, table: string): Promise<Record<string, HLCTimestamp>>;
101
124
  /**
102
- * Pull-side synthesis: return rows updated after `sinceHlcStr` (or `cursor`
103
- * if higher) in HLC order, paginated. `updated_at` is a serialized HLC
104
- * whose lexicographic order matches HLC order (fixed-width hex), and each
105
- * row's HLC is unique per node, so it doubles as the cursor — no separate
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, sinceHlcStr: string, options?: ScanSinceOptions): Promise<ScanSincePage>;
109
- /** Support read path from the factory's queryRows. */
110
- queryRows(appId: string, table: string, where?: Record<string, unknown>): Record<string, unknown>[];
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, SqliteDatabaseAdapter, type SqliteDatabaseAdapterOptions, 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,70 +1,57 @@
1
- import { DatabaseSync } from 'node:sqlite';
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 { 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';
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
- declare function initializeLocalSchema(db: DatabaseSync): void;
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: DatabaseSync, appId: string, tables: AppSyncableTableInfo[], filesEnabled: boolean): void;
65
- declare function deleteAppSyncableNamespace(db: DatabaseSync, appId: string): void;
66
- declare function getAppSyncableNamespace(db: DatabaseSync, appId: string): AppSyncableNamespace | null;
67
- declare function listAppSyncableNamespaces(db: DatabaseSync): AppSyncableNamespace[];
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: DatabaseSync);
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: DatabaseSync, namespace: AppSyncableNamespaceStore);
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
- /** 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
+ */
100
123
  getNodeWatermarks(appId: string, table: string): Promise<Record<string, HLCTimestamp>>;
101
124
  /**
102
- * Pull-side synthesis: return rows updated after `sinceHlcStr` (or `cursor`
103
- * if higher) in HLC order, paginated. `updated_at` is a serialized HLC
104
- * whose lexicographic order matches HLC order (fixed-width hex), and each
105
- * row's HLC is unique per node, so it doubles as the cursor — no separate
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, sinceHlcStr: string, options?: ScanSinceOptions): Promise<ScanSincePage>;
109
- /** Support read path from the factory's queryRows. */
110
- queryRows(appId: string, table: string, where?: Record<string, unknown>): Record<string, unknown>[];
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, SqliteDatabaseAdapter, type SqliteDatabaseAdapterOptions, 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 };