@syncular/server 0.58.0 → 0.60.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.
Files changed (103) hide show
  1. package/README.md +49 -36
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +46 -40
  4. package/dist/blob-handlers.d.ts +25 -31
  5. package/dist/blob-handlers.js +63 -41
  6. package/dist/blob-store.d.ts +42 -24
  7. package/dist/blob-store.js +0 -0
  8. package/dist/bucket-blob-store.d.ts +12 -8
  9. package/dist/bucket-blob-store.js +54 -45
  10. package/dist/bucket-segment-store.js +18 -16
  11. package/dist/content-encoding.d.ts +5 -2
  12. package/dist/content-encoding.js +42 -13
  13. package/dist/context.d.ts +19 -5
  14. package/dist/context.js +19 -1
  15. package/dist/d1-storage.d.ts +14 -98
  16. package/dist/d1-storage.js +249 -1119
  17. package/dist/errors.js +16 -0
  18. package/dist/events.d.ts +36 -18
  19. package/dist/frame-bytes.js +24 -6
  20. package/dist/handler.js +503 -208
  21. package/dist/local-authority.d.ts +2 -0
  22. package/dist/local-authority.js +24 -12
  23. package/dist/object-bucket.d.ts +2 -0
  24. package/dist/operations-realtime.js +69 -50
  25. package/dist/operations.d.ts +5 -2
  26. package/dist/operations.js +20 -29
  27. package/dist/pg-executor-pglite.d.ts +5 -6
  28. package/dist/pg-executor-pglite.js +22 -14
  29. package/dist/pg-executor.d.ts +4 -1
  30. package/dist/postgres-storage.d.ts +24 -19
  31. package/dist/postgres-storage.js +420 -262
  32. package/dist/pull.d.ts +70 -47
  33. package/dist/pull.js +270 -301
  34. package/dist/push.d.ts +12 -3
  35. package/dist/push.js +361 -173
  36. package/dist/realtime.d.ts +85 -39
  37. package/dist/realtime.js +355 -219
  38. package/dist/relational-rows.d.ts +21 -66
  39. package/dist/relational-rows.js +28 -109
  40. package/dist/s3-blob-store.d.ts +11 -12
  41. package/dist/s3-blob-store.js +20 -13
  42. package/dist/s3-object-bucket.d.ts +8 -1
  43. package/dist/s3-object-bucket.js +16 -3
  44. package/dist/schema.d.ts +14 -0
  45. package/dist/schema.js +23 -0
  46. package/dist/scopes.d.ts +6 -2
  47. package/dist/scopes.js +22 -4
  48. package/dist/seed.js +10 -16
  49. package/dist/segment-download.d.ts +4 -1
  50. package/dist/segment-download.js +22 -6
  51. package/dist/signed-url.d.ts +2 -2
  52. package/dist/signed-url.js +9 -2
  53. package/dist/sigv4.d.ts +8 -2
  54. package/dist/sigv4.js +8 -4
  55. package/dist/sqlite-blob-store.d.ts +1 -1
  56. package/dist/sqlite-blob-store.js +23 -22
  57. package/dist/sqlite-dialect.d.ts +164 -84
  58. package/dist/sqlite-dialect.js +1145 -150
  59. package/dist/sqlite-lease-store.js +13 -18
  60. package/dist/sqlite-storage.d.ts +9 -62
  61. package/dist/sqlite-storage.js +303 -1123
  62. package/dist/storage-query.d.ts +30 -1
  63. package/dist/storage-query.js +68 -0
  64. package/dist/storage.d.ts +185 -63
  65. package/dist/storage.js +15 -0
  66. package/package.json +2 -2
  67. package/src/admin.ts +99 -57
  68. package/src/blob-handlers.ts +91 -72
  69. package/src/blob-store.ts +0 -0
  70. package/src/bucket-blob-store.ts +75 -48
  71. package/src/bucket-segment-store.ts +20 -15
  72. package/src/content-encoding.ts +48 -16
  73. package/src/context.ts +33 -6
  74. package/src/d1-storage.ts +350 -1700
  75. package/src/errors.ts +16 -0
  76. package/src/events.ts +37 -18
  77. package/src/frame-bytes.ts +26 -6
  78. package/src/handler.ts +654 -261
  79. package/src/local-authority.ts +27 -14
  80. package/src/object-bucket.ts +2 -0
  81. package/src/operations-realtime.ts +85 -61
  82. package/src/operations.ts +44 -42
  83. package/src/pg-executor-pglite.ts +27 -23
  84. package/src/pg-executor.ts +5 -1
  85. package/src/postgres-storage.ts +557 -354
  86. package/src/pull.ts +406 -440
  87. package/src/push.ts +466 -220
  88. package/src/realtime.ts +447 -290
  89. package/src/relational-rows.ts +43 -121
  90. package/src/s3-blob-store.ts +23 -13
  91. package/src/s3-object-bucket.ts +20 -2
  92. package/src/schema.ts +31 -0
  93. package/src/scopes.ts +23 -3
  94. package/src/seed.ts +13 -20
  95. package/src/segment-download.ts +33 -7
  96. package/src/signed-url.ts +10 -4
  97. package/src/sigv4.ts +17 -4
  98. package/src/sqlite-blob-store.ts +27 -26
  99. package/src/sqlite-dialect.ts +1851 -199
  100. package/src/sqlite-lease-store.ts +12 -23
  101. package/src/sqlite-storage.ts +390 -1821
  102. package/src/storage-query.ts +102 -0
  103. package/src/storage.ts +215 -67
package/dist/seed.js CHANGED
@@ -9,7 +9,7 @@
9
9
  * Idempotent by construction (§2.3): the commit id is stable, so re-running
10
10
  * the seed replays the cached push result and writes nothing twice.
11
11
  */
12
- import { decodeMessage, encodeMessage, encodeSparseRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
12
+ import { decodeResponse, encodeRequest, encodeSparseRow, PROTOCOL_WIRE_VERSION, registrationDigest, } from '@syncular/core';
13
13
  import { SyncError } from './errors.js';
14
14
  import { composeEvents } from './events-ring.js';
15
15
  import { handleSyncRequest } from './handler.js';
@@ -111,7 +111,7 @@ export async function seedMutations(config, target, mutations) {
111
111
  partition: target.partition,
112
112
  actorId: target.actorId,
113
113
  };
114
- const acquisition = decodeMessage(await handleSyncRequest(encodeMessage({
114
+ const acquisition = decodeResponse(await handleSyncRequest(encodeRequest({
115
115
  wireVersion: PROTOCOL_WIRE_VERSION,
116
116
  msgKind: 'request',
117
117
  frames: [
@@ -126,13 +126,14 @@ export async function seedMutations(config, target, mutations) {
126
126
  limitSnapshotRows: 0,
127
127
  maxSnapshotPages: 0,
128
128
  accept: 0b0011,
129
+ cursor: -1,
130
+ registrationDigest: registrationDigest([]),
131
+ echoDigest: new Uint8Array(),
129
132
  },
130
133
  ],
131
134
  }), requestContext));
132
135
  const acquisitionHeader = acquisition.frames[0];
133
- if (acquisition.msgKind !== 'response' ||
134
- acquisitionHeader?.type !== 'RESP_HEADER' ||
135
- acquisitionHeader.logEpoch === undefined) {
136
+ if (acquisitionHeader?.type !== 'RESP_HEADER') {
136
137
  throw new SyncError('sync.invalid_request', 'seedMutations: epoch acquisition returned an invalid response');
137
138
  }
138
139
  const frames = [
@@ -142,15 +143,8 @@ export async function seedMutations(config, target, mutations) {
142
143
  schemaVersion: config.schema.version,
143
144
  logEpoch: acquisitionHeader.logEpoch,
144
145
  },
145
- { type: 'PUSH_COMMIT', clientCommitId, operations },
146
- // A pull that asks for nothing: the round exists for its push half.
147
- {
148
- type: 'PULL_HEADER',
149
- limitCommits: 0,
150
- limitSnapshotRows: 0,
151
- maxSnapshotPages: 0,
152
- accept: 0b0011,
153
- },
146
+ // §6.10: a database-less producer sends no outboxId and clientSeq 0.
147
+ { type: 'PUSH_COMMIT', clientCommitId, clientSeq: 0, operations },
154
148
  ];
155
149
  let terminalEvent;
156
150
  const capture = {
@@ -162,7 +156,7 @@ export async function seedMutations(config, target, mutations) {
162
156
  }
163
157
  },
164
158
  };
165
- const response = await handleSyncRequest(encodeMessage({
159
+ const response = await handleSyncRequest(encodeRequest({
166
160
  wireVersion: PROTOCOL_WIRE_VERSION,
167
161
  msgKind: 'request',
168
162
  frames,
@@ -173,7 +167,7 @@ export async function seedMutations(config, target, mutations) {
173
167
  : composeEvents(config.events, capture),
174
168
  });
175
169
  // Fail loud: surface the first rejected/failed operation.
176
- const message = decodeMessage(response);
170
+ const message = decodeResponse(response);
177
171
  const result = message.frames.find((frame) => frame.type === 'PUSH_RESULT' && frame.clientCommitId === clientCommitId);
178
172
  if (result === undefined) {
179
173
  throw new SyncError('sync.invalid_request', 'seedMutations: the sync response carried no push result');
@@ -2,7 +2,10 @@ import type { SyncRequestContext } from './context.js';
2
2
  import { type SegmentRecord } from './segment-store.js';
3
3
  export interface SegmentDownloadRequest {
4
4
  readonly segmentId: string;
5
- /** The `X-Syncular-Scopes` header: canonical JSON of the requested map. */
5
+ /**
6
+ * The `X-Syncular-Scopes` header: canonical JSON of the owning unit's scope
7
+ * map, each value as a one-element list (§5.5).
8
+ */
6
9
  readonly scopesHeader: string;
7
10
  }
8
11
  export interface SegmentDownloadResult {
@@ -18,9 +18,11 @@ function parseScopesHeader(header) {
18
18
  }
19
19
  const scopes = {};
20
20
  for (const [key, value] of Object.entries(parsed)) {
21
+ // §5.5: the owning unit's scope map, each value as a one-element list.
21
22
  if (!Array.isArray(value) ||
22
- value.some((v) => typeof v !== 'string')) {
23
- throw syncError('sync.invalid_request', 'X-Syncular-Scopes values must be string lists (§0)');
23
+ value.length !== 1 ||
24
+ typeof value[0] !== 'string') {
25
+ throw syncError('sync.invalid_request', 'X-Syncular-Scopes values must be one-element string lists (§5.5)');
24
26
  }
25
27
  scopes[key] = value;
26
28
  }
@@ -161,14 +163,28 @@ async function authorizePublication(ctx, request, logEpoch, stored) {
161
163
  }
162
164
  resolved = { ok: false };
163
165
  }
164
- const outcome = computeEffective(requested, resolved);
165
- if (outcome.status !== 'active') {
166
+ // §3.2: the effective scopes, and so the digest, depend on the declared
167
+ // variables of the publication's table (the wildcard fence).
168
+ const digests = new Map();
169
+ for (const publication of inContext) {
170
+ const key = `${publication.schemaVersion}\u0000${publication.table}`;
171
+ if (digests.has(key))
172
+ continue;
173
+ const table = schemaWindowOf(ctx.schema, ctx.schemaWindow)
174
+ .find((candidate) => candidate.version === publication.schemaVersion)
175
+ ?.tables.get(publication.table);
176
+ const outcome = computeEffective(table?.declaredVariables ?? new Set(), requested, resolved);
177
+ digests.set(key, outcome.status === 'active'
178
+ ? await scopeDigest(outcome.effective)
179
+ : undefined);
180
+ }
181
+ if ([...digests.values()].every((digest) => digest === undefined)) {
166
182
  throw syncError('sync.forbidden', 'segment scopes not held (§5.5)');
167
183
  }
168
- const digest = await scopeDigest(outcome.effective);
169
184
  // The digest is the grant, but only inside the caller's partition and live
170
185
  // epoch: identical bytes published elsewhere never authorize this caller.
171
- const forDigest = inContext.filter((publication) => publication.scopeDigest === digest);
186
+ const forDigest = inContext.filter((publication) => digests.get(`${publication.schemaVersion}\u0000${publication.table}`) ===
187
+ publication.scopeDigest);
172
188
  if (forDigest.length === 0) {
173
189
  throw syncError('sync.forbidden', 'scope digest mismatch (§3.5, §5.5)');
174
190
  }
@@ -87,8 +87,8 @@ export declare function issueBlobUrl(config: BlobPresignConfig, args: {
87
87
  * twin of `BlobPresignConfig`: the provider signs a single PUT whose object
88
88
  * key embeds the `blobId`. Issuance happens ONLY after host authentication in
89
89
  * the upload-grant handler (uploading is host-auth-only, not scope-bearing —
90
- * §5.9.3). The `byteLength` rides through so a provider MAY bind
91
- * `Content-Length` (S3 conditional) to the granted size. Never a multipart or
90
+ * §5.9.3). The provider MUST bind the PUT to the granted `byteLength` and to
91
+ * the content address, so the object store rejects other bytes. Never a multipart or
92
92
  * chunk protocol — single PUT only, this rung and the next (§5.9.3 non-goal).
93
93
  * `S3BlobStore.presignBlobPut` (via `s3PresignedBlobUploads`) is the in-tree
94
94
  * implementation.
@@ -120,8 +120,15 @@ export async function verifySegmentToken(key, token, expected) {
120
120
  const dot = token.indexOf('.');
121
121
  if (dot < 0)
122
122
  throw forbidden('malformed token');
123
- const payload = fromBase64url(token.slice(0, dot));
124
- const mac = fromBase64url(token.slice(dot + 1));
123
+ let payload;
124
+ let mac;
125
+ try {
126
+ payload = fromBase64url(token.slice(0, dot));
127
+ mac = fromBase64url(token.slice(dot + 1));
128
+ }
129
+ catch {
130
+ throw forbidden('malformed token');
131
+ }
125
132
  const computed = await hmac(key, payload);
126
133
  if (!constantTimeEqual(mac, computed))
127
134
  throw forbidden('bad MAC');
package/dist/sigv4.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Minimal AWS Signature Version 4 — exactly the subset the S3 segment
3
- * store needs (header-signed requests and presigned GET URLs), hand-rolled
3
+ * and blob stores need (header-signed requests and presigned URLs), hand-rolled
4
4
  * per the dependency-light doctrine: SigV4 is small and
5
5
  * well-specified, so no SDK.
6
6
  *
@@ -90,6 +90,12 @@ export interface PresignArgs {
90
90
  readonly credentials: SigV4Credentials;
91
91
  readonly nowMs: number;
92
92
  readonly expiresSeconds: number;
93
+ /**
94
+ * Headers the request must carry with exactly these values, signed beside
95
+ * `host` (a presigned PUT binds `content-length` and
96
+ * `x-amz-checksum-sha256`, so the store rejects other bytes).
97
+ */
98
+ readonly headers?: Readonly<Record<string, string>>;
93
99
  }
94
- /** Query-authenticated (presigned) URL; only the `host` header is signed. */
100
+ /** Query-authenticated (presigned) URL over `host` plus `headers`. */
95
101
  export declare function presignUrl(args: PresignArgs): Promise<URL>;
package/dist/sigv4.js CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Minimal AWS Signature Version 4 — exactly the subset the S3 segment
3
- * store needs (header-signed requests and presigned GET URLs), hand-rolled
3
+ * and blob stores need (header-signed requests and presigned URLs), hand-rolled
4
4
  * per the dependency-light doctrine: SigV4 is small and
5
5
  * well-specified, so no SDK.
6
6
  *
@@ -127,7 +127,7 @@ export async function signRequest(args) {
127
127
  authorization: `AWS4-HMAC-SHA256 Credential=${args.credentials.accessKeyId}/${scope},SignedHeaders=${signedHeaders},Signature=${signature}`,
128
128
  };
129
129
  }
130
- /** Query-authenticated (presigned) URL; only the `host` header is signed. */
130
+ /** Query-authenticated (presigned) URL over `host` plus `headers`. */
131
131
  export async function presignUrl(args) {
132
132
  const service = args.service ?? 's3';
133
133
  const method = args.method ?? 'GET';
@@ -138,7 +138,11 @@ export async function presignUrl(args) {
138
138
  url.searchParams.set('X-Amz-Credential', `${args.credentials.accessKeyId}/${scope}`);
139
139
  url.searchParams.set('X-Amz-Date', amzDate);
140
140
  url.searchParams.set('X-Amz-Expires', String(args.expiresSeconds));
141
- url.searchParams.set('X-Amz-SignedHeaders', 'host');
141
+ const headers = { ...args.headers, host: url.host };
142
+ url.searchParams.set('X-Amz-SignedHeaders', Object.keys(headers)
143
+ .map((name) => name.toLowerCase())
144
+ .sort()
145
+ .join(';'));
142
146
  if (args.credentials.sessionToken !== undefined) {
143
147
  url.searchParams.set('X-Amz-Security-Token', args.credentials.sessionToken);
144
148
  }
@@ -146,7 +150,7 @@ export async function presignUrl(args) {
146
150
  method,
147
151
  canonicalPath: url.pathname,
148
152
  query: url.searchParams,
149
- headers: { host: url.host },
153
+ headers,
150
154
  payloadHash: UNSIGNED_PAYLOAD,
151
155
  });
152
156
  const signature = await sigV4Signature({
@@ -13,6 +13,6 @@ export declare class SqliteBlobStore implements BlobStore {
13
13
  record: BlobRecord;
14
14
  bytes: Uint8Array;
15
15
  } | undefined>;
16
- sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
16
+ sweepOrphans(partition: string, olderThanMs: number, isReferenced: (blobId: string) => Promise<boolean>): Promise<string[]>;
17
17
  stats(partition: string): Promise<BlobStoreStats>;
18
18
  }
@@ -16,29 +16,27 @@ export class SqliteBlobStore {
16
16
  `);
17
17
  }
18
18
  async put(partition, blobId, bytes, nowMs, mediaType) {
19
- const existing = await this.get(partition, blobId);
20
- if (existing !== undefined) {
21
- if (existing.record.mediaType !== undefined || mediaType === undefined)
22
- return existing.record;
23
- // A re-upload names the media type an earlier upload left out.
24
- this.db
25
- .query('UPDATE sync_blobs SET media_type=? WHERE partition=? AND blob_id=? AND media_type IS NULL')
26
- .run(mediaType, partition, blobId);
27
- return { ...existing.record, mediaType };
19
+ // A re-upload refreshes the sweep grace clock and names the media type an
20
+ // earlier upload left out; it never replaces a recorded one.
21
+ const row = this.db
22
+ .query(`INSERT INTO sync_blobs(
23
+ partition, blob_id, byte_length, media_type, created_at_ms, bytes
24
+ ) VALUES (?,?,?,?,?,?)
25
+ ON CONFLICT(partition, blob_id) DO UPDATE SET
26
+ media_type = coalesce(media_type, excluded.media_type),
27
+ created_at_ms = max(created_at_ms, excluded.created_at_ms)
28
+ RETURNING media_type, created_at_ms`)
29
+ .get(partition, blobId, bytes.length, mediaType ?? null, nowMs, bytes);
30
+ if (row === null) {
31
+ throw new Error('SqliteBlobStore: blob upsert returned no row');
28
32
  }
29
- const record = {
33
+ return {
30
34
  blobId,
31
35
  partition,
32
36
  byteLength: bytes.length,
33
- ...(mediaType !== undefined ? { mediaType } : {}),
34
- createdAtMs: nowMs,
37
+ ...(row.media_type !== null ? { mediaType: row.media_type } : {}),
38
+ createdAtMs: row.created_at_ms,
35
39
  };
36
- this.db
37
- .query(`INSERT OR IGNORE INTO sync_blobs(
38
- partition, blob_id, byte_length, media_type, created_at_ms, bytes
39
- ) VALUES (?,?,?,?,?,?)`)
40
- .run(partition, blobId, bytes.length, mediaType ?? null, nowMs, bytes);
41
- return record;
42
40
  }
43
41
  async delete(partition, blobId) {
44
42
  this.db
@@ -69,16 +67,19 @@ export class SqliteBlobStore {
69
67
  bytes: new Uint8Array(row.bytes),
70
68
  };
71
69
  }
72
- async sweepOrphans(partition, olderThanMs, referencedBlobIds) {
70
+ async sweepOrphans(partition, olderThanMs, isReferenced) {
73
71
  const candidates = this.db
74
72
  .query(`SELECT blob_id FROM sync_blobs
75
73
  WHERE partition=? AND created_at_ms < ?`)
76
74
  .all(partition, olderThanMs);
77
75
  const swept = [];
78
- const del = this.db.query('DELETE FROM sync_blobs WHERE partition=? AND blob_id=?');
76
+ // The age condition repeats in the DELETE: a re-upload during the
77
+ // reference lookup refreshed the grace clock and keeps the blob.
78
+ const del = this.db.query('DELETE FROM sync_blobs WHERE partition=? AND blob_id=? AND created_at_ms < ?');
79
79
  for (const { blob_id } of candidates) {
80
- if (!referencedBlobIds.has(blob_id)) {
81
- del.run(partition, blob_id);
80
+ if (await isReferenced(blob_id))
81
+ continue;
82
+ if (del.run(partition, blob_id, olderThanMs).changes > 0) {
82
83
  swept.push(blob_id);
83
84
  }
84
85
  }
@@ -1,22 +1,24 @@
1
1
  /**
2
2
  * Shared SQLite dialect for synchronous `SqliteServerStorage` on Bun or Node
3
3
  * and asynchronous `D1ServerStorage` on Cloudflare Workers. D1 is SQLite:
4
- * same DDL, same statement grammar,
5
- * same `?` positional placeholders, same `INSERT ... ON CONFLICT` / `INSERT
6
- * OR IGNORE` upsert idioms — so the schema and the value (de)serialization are
7
- * genuinely common ground and live here.
4
+ * same DDL, same statement grammar, same `?` positional placeholders, same
5
+ * `INSERT ... ON CONFLICT` / `INSERT OR IGNORE` upsert idioms.
8
6
  *
9
- * What is not shared: statement execution. The server SQLite driver is sync
10
- * (`db.query(sql).get(...)`) and D1 is async (`await
11
- * db.prepare(sql).bind(...).all()`); a shared execution layer would have to
12
- * pick one calling convention and adapt the other, which is uglier than two
13
- * thin storage classes that each speak their driver's native shape while
14
- * importing the same SQL text and codecs from here.
15
- * Both classes run the identical `test/storage-contract.ts`, so the
16
- * behavior is held key-for-key regardless.
7
+ * `SqliteFamilyStorage` and `SqliteFamilyTransaction` hold every statement
8
+ * and row mapping the two backends share. A backend supplies statement
9
+ * execution through a small seam (`all`, `guardedAll`, `atomic`; `run` and
10
+ * `all` inside a transaction) and keeps only what differs: connection
11
+ * handling, the request lock in SQLite, transaction execution (interactive
12
+ * `BEGIN IMMEDIATE` in SQLite, one buffered `db.batch` in D1), D1's
13
+ * bound-parameter cap and its published-schema guard. The seam returns
14
+ * promises; the synchronous SQLite driver resolves them with rows it read at
15
+ * call time. Both classes run the identical `test/storage-contract.ts`.
17
16
  */
18
- import type { ScopeMap } from '@syncular/core';
19
- import type { ScopeValueHistoryQuery, StoredChange, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
17
+ import type { UnitScopes } from '@syncular/core';
18
+ import { type BoundAuthoritativeQuery } from './authoritative-query.js';
19
+ import type { CompiledTable } from './schema.js';
20
+ import type { SqliteValue } from './sqlite-driver.js';
21
+ import type { AuthoritativeQueryRequest, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitPruneQuery, CommitPruneResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, NewCommit, OutboxSequence, OutboxSettlement, NewReaction, PartitionRegistryEntry, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, StoredChange, StoredPushResult, StoredReaction, StoredRow, Tombstone } from './storage.js';
20
22
  /**
21
23
  * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
22
24
  * the whole string via `db.exec(SQLITE_DDL)`; D1 applies each statement
@@ -30,47 +32,34 @@ import type { ScopeValueHistoryQuery, StoredChange, StoredCommit, StoredPushResu
30
32
  * the Postgres storage documents (§3.1, performance-by-
31
33
  * construction).
32
34
  *
33
- * `sync_row_scopes_by_row` is the one secondary scope index: a per-row
34
- * scope replacement predicates on `(partition, tbl, row_id)`, and `row_id`
35
- * is the LAST PRIMARY KEY column, so that predicate cannot narrow the
36
- * inverted index. Declared here so every SQLite-family storage (and D1,
37
- * which applies this same DDL) keeps the same plan shape as Postgres.
35
+ * Changes to the core tables of an existing database (added and dropped
36
+ * columns and indexes) live in `sqliteUpgradeDdl`, which runs after this DDL.
38
37
  */
39
- export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n partition TEXT PRIMARY KEY,\n max_commit_seq INTEGER NOT NULL DEFAULT 0,\n horizon_seq INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n partition TEXT PRIMARY KEY,\n log_epoch TEXT NOT NULL,\n epoch_required INTEGER NOT NULL DEFAULT 0,\n last_authenticated_at_ms INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n partition TEXT NOT NULL, tbl TEXT NOT NULL,\n var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE INDEX IF NOT EXISTS sync_row_scopes_by_row\n ON sync_row_scopes(partition, tbl, row_id);\nCREATE TABLE IF NOT EXISTS sync_commits(\n partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n writer_version INTEGER,\n PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n partition TEXT NOT NULL, tbl TEXT NOT NULL,\n var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n partition TEXT NOT NULL, client_id TEXT NOT NULL,\n client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n last_failure TEXT,\n PRIMARY KEY(partition, idempotency_key),\n CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n wire_version INTEGER NOT NULL DEFAULT 1,\n cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n updated_at_ms INTEGER NOT NULL,\n last_round_at_ms INTEGER, last_error_code TEXT,\n consecutive_failures INTEGER NOT NULL DEFAULT 0,\n PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n blob_id TEXT NOT NULL,\n PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n commit_seq INTEGER NOT NULL,\n PRIMARY KEY(partition, tbl, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(\n partition TEXT NOT NULL, name TEXT NOT NULL,\n schema_version INTEGER NOT NULL,\n state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),\n watermark INTEGER NOT NULL DEFAULT 0,\n owner_epoch INTEGER NOT NULL DEFAULT 0,\n observed_rows INTEGER NOT NULL DEFAULT 0,\n updated_at_ms INTEGER NOT NULL,\n PRIMARY KEY(partition, name)\n);\nCREATE TABLE IF NOT EXISTS sync_writer_fence(\n partition TEXT PRIMARY KEY,\n required_writer_version INTEGER NOT NULL\n);\n";
40
- /** Columns added to `sync_clients` after its first release, by column name. */
41
- export declare const SYNC_CLIENT_ROUND_COLUMNS: {
42
- readonly last_round_at_ms: 'INTEGER';
43
- readonly last_error_code: 'TEXT';
44
- readonly consecutive_failures: 'INTEGER NOT NULL DEFAULT 0';
45
- };
46
- /** Split the DDL into individual statements (D1 applies them one by one). */
47
- export declare function sqliteDdlStatements(): string[];
48
- /** §4.6.1: rowIds of one table bound to one scope value, budgeted. */
49
- export declare const LIST_SCOPE_VALUE_ROWS_SQLITE_SQL = "SELECT row_id FROM sync_row_scopes WHERE partition=? AND tbl=? AND var=? AND value=? ORDER BY row_id LIMIT ?";
38
+ export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n partition TEXT PRIMARY KEY,\n max_commit_seq INTEGER NOT NULL DEFAULT 0,\n horizon_seq INTEGER NOT NULL DEFAULT 0,\n delete_floor INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n partition TEXT PRIMARY KEY,\n log_epoch TEXT NOT NULL,\n epoch_required INTEGER NOT NULL DEFAULT 0,\n last_authenticated_at_ms INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n partition TEXT NOT NULL, tbl TEXT NOT NULL,\n var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n writer_version INTEGER,\n PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n partition TEXT NOT NULL, tbl TEXT NOT NULL,\n var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n partition TEXT NOT NULL, client_id TEXT NOT NULL,\n client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n outbox_id TEXT, client_seq INTEGER,\n PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_push_watermarks(\n partition TEXT NOT NULL, client_id TEXT NOT NULL, outbox_id TEXT NOT NULL,\n through_seq INTEGER NOT NULL,\n PRIMARY KEY(partition, client_id, outbox_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n last_failure TEXT,\n PRIMARY KEY(partition, idempotency_key),\n CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n wire_version INTEGER NOT NULL DEFAULT 1,\n cursor INTEGER NOT NULL,\n updated_at_ms INTEGER NOT NULL,\n last_round_at_ms INTEGER, last_error_code TEXT,\n consecutive_failures INTEGER NOT NULL DEFAULT 0,\n schema_version INTEGER, units TEXT, registration_digest BLOB,\n catching_up TEXT NOT NULL DEFAULT '[]',\n PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n blob_id TEXT NOT NULL,\n PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n commit_seq INTEGER NOT NULL, server_version INTEGER, scopes TEXT,\n PRIMARY KEY(partition, tbl, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(\n partition TEXT NOT NULL, name TEXT NOT NULL,\n schema_version INTEGER NOT NULL,\n state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),\n watermark INTEGER NOT NULL DEFAULT 0,\n owner_epoch INTEGER NOT NULL DEFAULT 0,\n observed_rows INTEGER NOT NULL DEFAULT 0,\n updated_at_ms INTEGER NOT NULL,\n PRIMARY KEY(partition, name)\n);\nCREATE TABLE IF NOT EXISTS sync_writer_fence(\n partition TEXT PRIMARY KEY,\n required_writer_version INTEGER NOT NULL\n);\n";
50
39
  /**
51
- * §4.6.1 history scrub, bound by `eraseScopeValueHistoryParams`: upsert change
52
- * records of the binding first, then the change scope entries whose commit
53
- * no longer holds a change of the binding. Each returns one row per removed
54
- * record (D1 batch results carry no reliable change count).
40
+ * One statement that reads what `sqliteUpgradeDdl` needs: the columns of
41
+ * every table with added or dropped columns, and which added indexes exist.
55
42
  */
56
- export declare const ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL: readonly [`DELETE FROM sync_changes WHERE rowid IN (
57
- SELECT c.rowid FROM sync_change_scopes s JOIN sync_changes c
58
- ON c.partition=s.partition AND c.commit_seq=s.commit_seq AND c.tbl=s.tbl
59
- WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
60
- AND s.commit_seq<=?5 AND c.op=1 AND json_extract(c.scopes, ?6)=s.value
61
- LIMIT ?7) RETURNING 1 AS removed`, `DELETE FROM sync_change_scopes WHERE rowid IN (
62
- SELECT s.rowid FROM sync_change_scopes s
63
- WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
64
- AND s.commit_seq<=?5 AND NOT EXISTS (
65
- SELECT 1 FROM sync_changes c
66
- WHERE c.partition=s.partition AND c.commit_seq=s.commit_seq
67
- AND c.tbl=s.tbl AND json_extract(c.scopes, ?6)=s.value)
68
- LIMIT ?7) RETURNING 1 AS removed`];
69
- export declare function eraseScopeValueHistoryParams(partition: string, query: ScopeValueHistoryQuery): [string, string, string, string, number, string, number];
43
+ export declare const SQLITE_UPGRADE_PROBE: SqliteStatementSpec;
44
+ /**
45
+ * The statements that bring the core tables of a database from an earlier
46
+ * release to the current DDL, given the `SQLITE_UPGRADE_PROBE` rows: missing
47
+ * columns, dropped columns, dropped indexes, then missing indexes. Empty for
48
+ * a current database. Run after `SQLITE_DDL`: on every `SqliteServerStorage`
49
+ * construction, and on D1 in `migrate()`, the core phase of `migrateSchema`
50
+ * and the first open of a database at the current schema version.
51
+ */
52
+ export declare function sqliteUpgradeDdl(present: readonly {
53
+ readonly tbl: string;
54
+ readonly name: string;
55
+ }[]): string[];
56
+ /** Split the DDL into individual statements (D1 applies them one by one). */
57
+ export declare function sqliteDdlStatements(): string[];
70
58
  /** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */
71
59
  export declare function placeholders(count: number): string;
72
60
  /** Serialize a push result to the JSON `TEXT` stored in `sync_push_results`. */
73
61
  export declare function serializePushResult(result: StoredPushResult): string;
62
+ /** Parse a stored push result; an unreadable record is a §6.3 cache miss. */
74
63
  export declare function deserializePushResult(text: string): StoredPushResult;
75
64
  /** Row-record shape the SQLite `SELECT`s in both storages return. */
76
65
  export interface SqliteRowRecord {
@@ -91,45 +80,136 @@ export interface SqliteChangeRecord {
91
80
  /** Native SQLite returns `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
92
81
  export declare function asUint8Array(value: unknown): Uint8Array;
93
82
  export declare function toStoredRow(record: SqliteRowRecord): StoredRow;
83
+ export interface SqliteTombstoneRecord {
84
+ commit_seq: number;
85
+ server_version: number | null;
86
+ scopes: string | null;
87
+ }
88
+ export declare function toTombstone(record: SqliteTombstoneRecord): Tombstone;
94
89
  export declare function toStoredChange(record: SqliteChangeRecord): StoredChange;
90
+ /** One statement of an atomic unit: its SQL text and bound parameters. */
91
+ export interface SqliteStatementSpec {
92
+ readonly sql: string;
93
+ readonly params: readonly SqliteValue[];
94
+ }
95
95
  /**
96
- * One result row of `commitWindowPageSql` (candidate LEFT JOIN commit meta
97
- * LEFT JOIN changes): meta/change columns are NULL when the joined row
98
- * vanished (see the builder's LEFT JOIN contract). `payload` is a BLOB —
99
- * Native SQLite hands back `Uint8Array`, D1 `ArrayBuffer`; `toStoredChange`
100
- * normalizes via `asUint8Array`.
96
+ * The `ServerStorage` methods SQLite and D1 share. A subclass supplies the
97
+ * execution seam and implements the rest of the interface: schema migration,
98
+ * `begin`, registered queries, the serve gate and checkpoints.
101
99
  */
102
- export interface SqliteCommitWindowRecord {
103
- commit_seq: number;
104
- actor_id: string | null;
105
- created_at_ms: number | null;
106
- tbl: string | null;
107
- row_id: string | null;
108
- op: number | null;
109
- row_version: number | null;
110
- scopes: string | null;
111
- payload: Uint8Array | null;
100
+ export declare abstract class SqliteFamilyStorage {
101
+ /** Set by `ensureSchema`: app-table lookup for the relational row store. */
102
+ protected tables: ReadonlyMap<string, CompiledTable> | undefined;
103
+ protected schemaVersion: number | undefined;
104
+ /** Bound parameters one statement accepts. */
105
+ protected abstract readonly maxBindParams: number;
106
+ /** Run one statement and return its rows. */
107
+ protected abstract all<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
108
+ /**
109
+ * Run one read of schema-dependent state (row tables, the commit window,
110
+ * push results). D1 runs it behind its published-schema guard and joins the
111
+ * reads of one microtask turn into one batch; SQLite runs it as `all`.
112
+ */
113
+ protected abstract guardedAll<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
114
+ /** Run statements as one all-or-nothing unit; returns each one's rows. */
115
+ protected abstract atomic(statements: readonly SqliteStatementSpec[]): Promise<unknown[][]>;
116
+ /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
117
+ table(name: string): CompiledTable;
118
+ protected prepareAuthoritativeQuery(partition: string, query: AuthoritativeQueryRequest): BoundAuthoritativeQuery;
119
+ touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
120
+ rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
121
+ listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
122
+ getMaxCommitSeq(partition: string): Promise<number>;
123
+ getPartitionLogEpoch(partition: string): Promise<string | undefined>;
124
+ getHorizonSeq(partition: string): Promise<number>;
125
+ setHorizonSeq(partition: string, seq: number): Promise<void>;
126
+ pruneCommitsThrough(partition: string, query: CommitPruneQuery): Promise<CommitPruneResult>;
127
+ getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
128
+ sourceCoverageSeq(partition: string, tables: readonly string[]): Promise<number>;
129
+ hasSourceChangesAbove(partition: string, tables: readonly string[], seq: number): Promise<'clean' | 'changed' | 'unverifiable'>;
130
+ getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
131
+ getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
132
+ claimReactions(partition: string, query: ReactionClaimQuery): Promise<StoredReaction[]>;
133
+ completeReaction(partition: string, idempotencyKey: string, leaseOwner: string, completedAtMs: number): Promise<boolean>;
134
+ extendReactionLease(partition: string, idempotencyKey: string, leaseOwner: string, leaseExpiresAtMs: number): Promise<boolean>;
135
+ failReaction(partition: string, idempotencyKey: string, update: ReactionFailureUpdate): Promise<boolean>;
136
+ retryReaction(partition: string, idempotencyKey: string, nowMs: number): Promise<boolean>;
137
+ getReaction(partition: string, idempotencyKey: string): Promise<StoredReaction | undefined>;
138
+ listReactions(partition: string, query: ReactionListQuery): Promise<StoredReaction[]>;
139
+ pruneReactions(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
140
+ latestScopedChangeSeq(partition: string, query: {
141
+ readonly table: string;
142
+ readonly scopes: UnitScopes;
143
+ }): Promise<number>;
144
+ readLiveWindow(partition: string, query: LiveWindowQuery): Promise<LiveWindow>;
145
+ scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
146
+ scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
147
+ getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
148
+ putClientRecord(partition: string, record: ClientRecord, options?: ClientRecordWriteOptions): Promise<void>;
149
+ recordClientRoundFailure(partition: string, clientId: string, actorId: string, errorCode: string, atMs: number): Promise<void>;
150
+ advanceClientCursor(partition: string, clientId: string, actorId: string, logEpoch: string, cursor: number, updatedAtMs: number): Promise<void>;
151
+ getActiveClientCursorFloor(partition: string, cutoffMs: number): Promise<number | null>;
152
+ listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
153
+ listRowsReferencingBlob(partition: string, blobId: string): Promise<{
154
+ readonly table: string;
155
+ readonly rowId: string;
156
+ readonly scopes: Record<string, string>;
157
+ }[]>;
158
+ listReferencedBlobIds(partition: string): Promise<string[]>;
159
+ listScopeValueRows(partition: string, query: ScopeValueQuery): Promise<string[]>;
160
+ eraseScopeValueHistory(partition: string, query: ScopeValueHistoryQuery): Promise<number>;
161
+ listClientRecords(partition: string): Promise<ClientRecord[]>;
162
+ listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
163
+ getCommit(partition: string, commitSeq: number): Promise<CommitDetail | undefined>;
164
+ listRowChanges(partition: string, query: RowChangesQuery): Promise<RowChangeRecord[]>;
165
+ listRows(partition: string, query: RowListQuery): Promise<StoredRow[]>;
166
+ countRows(partition: string, table: string): Promise<number>;
167
+ listPushResults(partition: string, clientCommitId: string): Promise<ClientPushResult[]>;
168
+ listPushWatermarks(partition: string, clientCommitId: string): Promise<PushWatermark[]>;
169
+ scopeActivity(partition: string, query: ScopeActivityQuery): Promise<ScopeCommitActivity[]>;
170
+ listPartitions(): Promise<string[]>;
112
171
  }
113
172
  /**
114
- * Fold one `commitWindowPageSql` page into commits, preserving the exact
115
- * semantics of the old per-candidate loop:
116
- *
117
- * - rows arrive ordered (commit_seq, idx); consecutive rows with the same
118
- * `commit_seq` are one candidate commit;
119
- * - every candidate advances the cursor (`lastSeq`) — including vanished
120
- * commits (NULL meta) and commits whose changes all fail the exact
121
- * multi-variable scope verification (`matchesEffective`);
122
- * - a commit is emitted only with its matching changes, in `idx` order;
123
- * - stops after the commit that accumulates at least `remaining` matching
124
- * changes (never splitting a commit).
125
- *
126
- * `candidateCount` counts the processed candidates so the caller can detect
127
- * a short page (window exhausted) exactly as it did with the old candidate
128
- * query.
173
+ * The `StorageTransaction` writes SQLite and D1 share. `run` executes a write
174
+ * at call time on SQLite, inside its `BEGIN IMMEDIATE`; D1 buffers it for the
175
+ * one `db.batch` at `commit()`.
129
176
  */
130
- export declare function collectCommitWindowPage(records: readonly SqliteCommitWindowRecord[], scopeFilter: ScopeMap, remaining: number): {
131
- commits: StoredCommit[];
132
- delivered: number;
133
- lastSeq: number;
134
- candidateCount: number;
135
- };
177
+ export declare abstract class SqliteFamilyTransaction {
178
+ protected readonly partition: string;
179
+ protected open: boolean;
180
+ constructor(partition: string);
181
+ /** Execute (SQLite) or buffer (D1) one write of this transaction. */
182
+ protected abstract run(sql: string, params: readonly SqliteValue[]): void;
183
+ /** Read persisted state from inside this transaction. */
184
+ protected abstract all<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
185
+ protected abstract table(name: string): CompiledTable;
186
+ /** Allocate the next dense commitSeq (§2.1) and write its `sync_commits` row. */
187
+ protected abstract appendCommitRow(commit: NewCommit): Promise<number>;
188
+ abstract getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
189
+ protected assertOpen(): void;
190
+ getRows(table: string, rowIds: readonly string[]): Promise<ReadonlyMap<string, StoredRow>>;
191
+ getTombstone(table: string, rowId: string): Promise<Tombstone | undefined>;
192
+ clearTombstone(table: string, rowId: string): Promise<void>;
193
+ /**
194
+ * Write a row and refresh its scope-index entries. The DELETE drops only
195
+ * the keys the new scope map no longer carries and runs before the upsert,
196
+ * so its subquery reads the pre-upsert scope map; keys present in both
197
+ * maps are left alone and the `INSERT OR IGNORE` writes nothing for them.
198
+ */
199
+ protected writeRow(table: string, row: StoredRow): void;
200
+ deleteRow(table: string, rowId: string): Promise<void>;
201
+ setBlobRefs(table: string, rowId: string, blobIds: readonly string[]): Promise<void>;
202
+ appendCommit(commit: NewCommit): Promise<number>;
203
+ putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult, sequence?: OutboxSequence): Promise<void>;
204
+ /**
205
+ * The §9 settlement and §6.3.2 steps 1 and 2 for one request, then the
206
+ * idempotency read of its first commit. The reads run before the writes,
207
+ * so D1, which buffers the writes until commit, answers exactly as SQLite:
208
+ * the first commit's result counts as deleted when the writes delete it.
209
+ */
210
+ protected settleOutbox(clientId: string, clientCommitId: string, outbox: OutboxSettlement): Promise<{
211
+ readonly watermark: number;
212
+ readonly persisted: StoredPushResult | undefined;
213
+ }>;
214
+ enqueueReactions(reactions: readonly NewReaction[]): Promise<void>;
215
+ }