@syncular/server 0.74.0 → 0.76.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 (47) hide show
  1. package/dist/admin.d.ts +6 -3
  2. package/dist/admin.js +10 -7
  3. package/dist/blob-handlers.js +2 -0
  4. package/dist/bucket-segment-store.d.ts +4 -3
  5. package/dist/bucket-segment-store.js +4 -2
  6. package/dist/context.d.ts +29 -1
  7. package/dist/context.js +23 -2
  8. package/dist/handler.js +7 -2
  9. package/dist/index.d.ts +1 -1
  10. package/dist/lease-store.d.ts +10 -3
  11. package/dist/lease-store.js +0 -0
  12. package/dist/operations.js +2 -0
  13. package/dist/pull.d.ts +9 -4
  14. package/dist/pull.js +129 -76
  15. package/dist/realtime.d.ts +14 -1
  16. package/dist/realtime.js +14 -3
  17. package/dist/segment-download.js +1 -0
  18. package/dist/segment-store.d.ts +6 -4
  19. package/dist/segment-store.js +4 -2
  20. package/dist/signed-url.d.ts +15 -0
  21. package/dist/signed-url.js +7 -2
  22. package/dist/sqlite-bun.js +2 -2
  23. package/dist/sqlite-image.d.ts +18 -3
  24. package/dist/sqlite-image.js +27 -5
  25. package/dist/sqlite-lease-store.d.ts +1 -1
  26. package/dist/sqlite-lease-store.js +19 -6
  27. package/dist/sqlite-node.js +3 -2
  28. package/dist/sqlite-segment-store.js +7 -7
  29. package/package.json +2 -2
  30. package/src/admin.ts +11 -5
  31. package/src/blob-handlers.ts +2 -0
  32. package/src/bucket-segment-store.ts +8 -5
  33. package/src/context.ts +38 -2
  34. package/src/handler.ts +9 -1
  35. package/src/index.ts +1 -0
  36. package/src/lease-store.ts +0 -0
  37. package/src/operations.ts +2 -0
  38. package/src/pull.ts +200 -94
  39. package/src/realtime.ts +26 -12
  40. package/src/segment-download.ts +1 -0
  41. package/src/segment-store.ts +10 -6
  42. package/src/signed-url.ts +22 -2
  43. package/src/sqlite-bun.ts +2 -2
  44. package/src/sqlite-image.ts +42 -7
  45. package/src/sqlite-lease-store.ts +22 -4
  46. package/src/sqlite-node.ts +3 -2
  47. package/src/sqlite-segment-store.ts +29 -7
@@ -5,9 +5,10 @@
5
5
  *
6
6
  * Native: `st = base64url(payloadJson) + "." +
7
7
  * base64url(HMAC-SHA256(key, payloadJson))` with claims
8
- * `{v, seg, sd, aud, exp}`; `exp` is unix seconds. Issuance happens inside
8
+ * `{v, seg, sd, aud, exp, ctx?}`; `exp` is unix seconds and `ctx` the
9
+ * authentication context of the issuing pull (§1.1). Issuance happens inside
9
10
  * the pull immediately after scope resolution; verification checks MAC,
10
- * expiry (≤ 60 s skew), and `seg`/`sd`/`aud` equality. Actual CDN serving
11
+ * expiry (≤ 60 s skew), and `seg`/`sd`/`aud`/`ctx` equality. Actual CDN serving
11
12
  * is out of scope.
12
13
  *
13
14
  * Delegated presign: the provider mints the URL (§5.4 equivalence rule —
@@ -35,6 +36,7 @@ export async function issueSegmentUrl(config, args) {
35
36
  sd: args.scopeDigest,
36
37
  aud: config.audience(args.partition),
37
38
  exp,
39
+ ...(args.context !== undefined ? { ctx: args.context } : {}),
38
40
  });
39
41
  return {
40
42
  url: `${config.baseUrl}/${args.segmentId}?st=${token}`,
@@ -99,6 +101,7 @@ export async function signSegmentToken(key, claims) {
99
101
  sd: claims.sd,
100
102
  aud: claims.aud,
101
103
  exp: claims.exp,
104
+ ...(claims.ctx !== undefined ? { ctx: claims.ctx } : {}),
102
105
  });
103
106
  const payload = encoder.encode(payloadJson);
104
107
  const mac = await hmac(key, payload);
@@ -155,5 +158,7 @@ export async function verifySegmentToken(key, token, expected) {
155
158
  throw forbidden('scope-digest mismatch');
156
159
  if (claims.aud !== expected.audience)
157
160
  throw forbidden('audience mismatch');
161
+ if (expected.context !== undefined && claims.ctx !== expected.context)
162
+ throw forbidden('context mismatch');
158
163
  return claims;
159
164
  }
@@ -30,8 +30,8 @@ export class SqliteLeaseStore extends SharedSqliteLeaseStore {
30
30
  export const buildSqliteImage = async (input) => {
31
31
  const db = new BunSqliteDatabase();
32
32
  try {
33
- await writeSqliteImage(db, input);
34
- return db.serialize();
33
+ const rowCount = await writeSqliteImage(db, input);
34
+ return { bytes: db.serialize(), rowCount };
35
35
  }
36
36
  finally {
37
37
  db.close();
@@ -10,6 +10,13 @@ export interface SqliteImageInput {
10
10
  readonly schemaVersion: number;
11
11
  readonly asOfCommitSeq: number;
12
12
  readonly scopeDigest: string;
13
+ /**
14
+ * The image's file-size bound (`ServerLimits.maxImageSegmentBytes`). The
15
+ * builder stops before the row that could pass it; the first row always
16
+ * goes in.
17
+ */
18
+ readonly maxBytes: number;
19
+ /** The range's rows in row order, from its start to the table's end. */
13
20
  readonly rowBatches: AsyncIterable<readonly StoredRow[]> | Iterable<readonly StoredRow[]>;
14
21
  }
15
22
  /**
@@ -20,6 +27,14 @@ export interface SqliteImageInput {
20
27
  * on the pull path. A Bun or Node host passes `buildSqliteImage`; a Workers
21
28
  * host omits it and serves matching stored images or the rows lane.
22
29
  */
23
- export type SqliteImageBuilder = (input: SqliteImageInput) => Promise<Uint8Array>;
24
- /** Populate a §5.3 image database for a whole-table snapshot. */
25
- export declare function writeSqliteImage(db: SqliteDatabase, input: SqliteImageInput): Promise<void>;
30
+ export type SqliteImageBuilder = (input: SqliteImageInput) => Promise<SqliteImage>;
31
+ /** A built image and the number of leading input rows it holds. */
32
+ export interface SqliteImage {
33
+ readonly bytes: Uint8Array;
34
+ readonly rowCount: number;
35
+ }
36
+ /**
37
+ * Populate a §5.3 image database with the leading input rows that fit
38
+ * `maxBytes`. Returns how many rows it consumed.
39
+ */
40
+ export declare function writeSqliteImage(db: SqliteDatabase, input: SqliteImageInput): Promise<number>;
@@ -1,8 +1,8 @@
1
1
  import { rollbackAfterError } from './storage-errors.js';
2
2
  /**
3
3
  * SQLite-image segment generation (SPEC.md §5.3): a complete SQLite
4
- * database file carrying one table's whole effective-scope snapshot at
5
- * the bootstrap pin, plus the single-row `_syncular_segment` metadata
4
+ * database file carrying one range of a table's effective-scope snapshot at
5
+ * the table's scope pin, plus the single-row `_syncular_segment` metadata
6
6
  * table. Runtime entries provide the concrete SQLite database.
7
7
  *
8
8
  * Images are NOT byte-deterministic (§5.3): the content address pins the
@@ -45,7 +45,10 @@ function toSql(value) {
45
45
  return value ? 1 : 0;
46
46
  return value;
47
47
  }
48
- /** Populate a §5.3 image database for a whole-table snapshot. */
48
+ /**
49
+ * Populate a §5.3 image database with the leading input rows that fit
50
+ * `maxBytes`. Returns how many rows it consumed.
51
+ */
49
52
  export async function writeSqliteImage(db, input) {
50
53
  const { table, rowBatches } = input;
51
54
  const primaryKey = table.columns[table.primaryKeyIndex]?.name;
@@ -66,18 +69,37 @@ export async function writeSqliteImage(db, input) {
66
69
  ];
67
70
  const insert = db.query(`INSERT INTO ${quoteIdent(table.name)} (${names.join(', ')})
68
71
  VALUES (${names.map(() => '?').join(', ')})`);
72
+ const pageSize = db
73
+ .query('PRAGMA page_size')
74
+ .get().page_size;
75
+ const pageCount = db.query('PRAGMA page_count');
69
76
  db.exec('BEGIN');
70
77
  try {
71
78
  let rowCount = 0;
72
- for await (const rows of rowBatches) {
79
+ // An upper bound of the file size, re-measured when it nears the bound.
80
+ let size = pageCount.get().page_count * pageSize;
81
+ fill: for await (const rows of rowBatches) {
73
82
  for (const row of rows) {
83
+ // An appended row grows the table and its primary-key index by at
84
+ // most its cell (bounded by the payload plus a 9-byte varint per
85
+ // column, the version and the rowid), overflow rounding and a split
86
+ // per tree level.
87
+ const growth = 2 * (row.payload.length + 9 * (table.columns.length + 2)) +
88
+ 16 * pageSize;
89
+ if (rowCount > 0 && size + growth > input.maxBytes) {
90
+ size = pageCount.get().page_count * pageSize;
91
+ if (size + growth > input.maxBytes)
92
+ break fill;
93
+ }
74
94
  const values = decodeRow(table.columns, row.payload);
75
95
  insert.run(...values.map(toSql), row.serverVersion);
96
+ size += growth;
97
+ rowCount += 1;
76
98
  }
77
- rowCount += rows.length;
78
99
  }
79
100
  db.query(`INSERT INTO ${IMAGE_METADATA_TABLE} VALUES (1, ?, ?, ?, ?, ?)`).run(table.name, input.schemaVersion, input.asOfCommitSeq, input.scopeDigest, rowCount);
80
101
  db.exec('COMMIT');
102
+ return rowCount;
81
103
  }
82
104
  catch (error) {
83
105
  rollbackAfterError(() => {
@@ -11,6 +11,6 @@ export declare class SqliteLeaseStore implements LeaseStore {
11
11
  readonly leaseId?: LeaseIdFactory;
12
12
  });
13
13
  get(partition: string, clientId: string): Promise<LeaseRecord | undefined>;
14
- issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
14
+ issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number, context?: string): Promise<LeaseRecord>;
15
15
  revoke(partition: string, leaseId: string): Promise<void>;
16
16
  }
@@ -17,6 +17,7 @@ export class SqliteLeaseStore {
17
17
  lease_id TEXT NOT NULL, actor_id TEXT NOT NULL,
18
18
  allowed_scopes TEXT NOT NULL,
19
19
  issued_at_ms INTEGER NOT NULL, expires_at_ms INTEGER NOT NULL,
20
+ context TEXT,
20
21
  PRIMARY KEY (partition, client_id)
21
22
  );
22
23
  CREATE TABLE IF NOT EXISTS sync_lease_revocations(
@@ -24,13 +25,21 @@ export class SqliteLeaseStore {
24
25
  PRIMARY KEY (partition, lease_id)
25
26
  );
26
27
  `);
28
+ // §7.3.1: a lease table created before leases recorded their
29
+ // authentication context gains the column; its rows carry none.
30
+ if (!this.db
31
+ .query(`PRAGMA table_info(sync_leases)`)
32
+ .all()
33
+ .some((column) => column.name === 'context')) {
34
+ this.db.exec(`ALTER TABLE sync_leases ADD COLUMN context TEXT`);
35
+ }
27
36
  }
28
37
  async get(partition, clientId) {
29
38
  const row = this.db
30
39
  .query(
31
40
  // §7.3.4: the revocation table is the only record of a revocation, so
32
41
  // a revoked id stays revoked whatever its lease row says.
33
- `SELECT l.lease_id, l.actor_id, l.allowed_scopes, l.issued_at_ms,
42
+ `SELECT l.lease_id, l.actor_id, l.context, l.allowed_scopes, l.issued_at_ms,
34
43
  l.expires_at_ms,
35
44
  EXISTS (SELECT 1 FROM sync_lease_revocations r
36
45
  WHERE r.partition=l.partition
@@ -42,21 +51,24 @@ export class SqliteLeaseStore {
42
51
  return {
43
52
  leaseId: row.lease_id,
44
53
  actorId: row.actor_id,
54
+ ...(row.context !== null ? { context: row.context } : {}),
45
55
  allowedScopes: JSON.parse(row.allowed_scopes),
46
56
  issuedAtMs: row.issued_at_ms,
47
57
  expiresAtMs: row.expires_at_ms,
48
58
  revoked: row.revoked !== 0,
49
59
  };
50
60
  }
51
- async issue(partition, clientId, actorId, allowedScopes, nowMs, ttlMs) {
61
+ async issue(partition, clientId, actorId, allowedScopes, nowMs, ttlMs, context) {
52
62
  const existing = await this.get(partition, clientId);
53
63
  const reuse = existing !== undefined &&
54
64
  existing.actorId === actorId &&
65
+ existing.context === context &&
55
66
  !existing.revoked;
56
67
  const leaseId = reuse ? existing.leaseId : this.#newId();
57
68
  const record = {
58
69
  leaseId,
59
70
  actorId,
71
+ ...(context !== undefined ? { context } : {}),
60
72
  allowedScopes,
61
73
  issuedAtMs: nowMs,
62
74
  expiresAtMs: nowMs + ttlMs,
@@ -65,14 +77,15 @@ export class SqliteLeaseStore {
65
77
  this.db
66
78
  .query(`INSERT INTO sync_leases(
67
79
  partition, client_id, lease_id, actor_id, allowed_scopes,
68
- issued_at_ms, expires_at_ms
69
- ) VALUES (?,?,?,?,?,?,?)
80
+ issued_at_ms, expires_at_ms, context
81
+ ) VALUES (?,?,?,?,?,?,?,?)
70
82
  ON CONFLICT(partition, client_id) DO UPDATE SET
71
83
  lease_id=excluded.lease_id, actor_id=excluded.actor_id,
72
84
  allowed_scopes=excluded.allowed_scopes,
73
85
  issued_at_ms=excluded.issued_at_ms,
74
- expires_at_ms=excluded.expires_at_ms`)
75
- .run(partition, clientId, leaseId, actorId, JSON.stringify(allowedScopes), nowMs, record.expiresAtMs);
86
+ expires_at_ms=excluded.expires_at_ms,
87
+ context=excluded.context`)
88
+ .run(partition, clientId, leaseId, actorId, JSON.stringify(allowedScopes), nowMs, record.expiresAtMs, context ?? null);
76
89
  return record;
77
90
  }
78
91
  async revoke(partition, leaseId) {
@@ -35,13 +35,14 @@ export const buildSqliteImage = async (input) => {
35
35
  const path = join(directory, 'segment.db');
36
36
  const db = new NodeSqliteDatabase(path);
37
37
  try {
38
+ let rowCount;
38
39
  try {
39
- await writeSqliteImage(db, input);
40
+ rowCount = await writeSqliteImage(db, input);
40
41
  }
41
42
  finally {
42
43
  db.close();
43
44
  }
44
- return new Uint8Array(readFileSync(path));
45
+ return { bytes: new Uint8Array(readFileSync(path)), rowCount };
45
46
  }
46
47
  finally {
47
48
  rmSync(directory, { recursive: true, force: true });
@@ -183,19 +183,19 @@ export class SqliteSegmentStore {
183
183
  const publication = this.db
184
184
  .query(`SELECT segment_id FROM sync_segment_publications
185
185
  WHERE partition=? AND log_epoch=? AND tbl=? AND schema_version=? AND media_type=?
186
- AND scope_digest=? AND as_of_commit_seq=? AND row_cursor IS NULL
186
+ AND scope_digest=? AND as_of_commit_seq=? AND row_cursor IS ?
187
187
  AND expires_at_ms > ?
188
- LIMIT 1`)
189
- .get(key.partition, key.logEpoch, key.table, key.schemaVersion, key.mediaType, key.scopeDigest, key.asOfCommitSeq, nowMs);
188
+ ORDER BY created_at_ms DESC LIMIT 1`)
189
+ .get(key.partition, key.logEpoch, key.table, key.schemaVersion, key.mediaType, key.scopeDigest, key.asOfCommitSeq, key.rowCursor, nowMs);
190
190
  const legacy = this.db
191
191
  .query(`SELECT s.segment_id
192
192
  FROM sync_segments s
193
193
  JOIN sync_segment_scopes sc ON sc.segment_id = s.segment_id
194
194
  WHERE s.partition=? AND s.log_epoch=? AND s.tbl=? AND s.schema_version=? AND s.media_type=?
195
- AND sc.scope_digest=? AND s.as_of_commit_seq=? AND s.row_cursor IS NULL
195
+ AND sc.scope_digest=? AND s.as_of_commit_seq=? AND s.row_cursor IS ?
196
196
  AND s.expires_at_ms > ?
197
- LIMIT 1`)
198
- .get(key.partition, key.logEpoch, key.table, key.schemaVersion, key.mediaType, key.scopeDigest, key.asOfCommitSeq, nowMs);
197
+ ORDER BY s.created_at_ms DESC LIMIT 1`)
198
+ .get(key.partition, key.logEpoch, key.table, key.schemaVersion, key.mediaType, key.scopeDigest, key.asOfCommitSeq, key.rowCursor, nowMs);
199
199
  const segmentId = publication?.segment_id ?? legacy?.segment_id;
200
200
  if (segmentId === undefined)
201
201
  return undefined;
@@ -210,7 +210,7 @@ export class SqliteSegmentStore {
210
210
  mediaType: key.mediaType,
211
211
  scopeDigest: key.scopeDigest,
212
212
  asOfCommitSeq: key.asOfCommitSeq,
213
- rowCursor: null,
213
+ rowCursor: key.rowCursor,
214
214
  nowMs,
215
215
  });
216
216
  if (match === undefined)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server",
3
- "version": "0.74.0",
3
+ "version": "0.76.0",
4
4
  "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
68
68
  "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
69
69
  },
70
70
  "dependencies": {
71
- "@syncular/core": "0.74.0"
71
+ "@syncular/core": "0.76.0"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@electric-sql/pglite": "^0.5.4"
package/src/admin.ts CHANGED
@@ -894,7 +894,8 @@ export class SyncularAdmin {
894
894
  * Trace whether one client receives one row, combining the row's stored
895
895
  * scopes and newest change with the client's units, cursor, the
896
896
  * actor's allowed scopes, and its retained push failures. See
897
- * `AdminTraceVerdict` for the verdict order.
897
+ * `AdminTraceVerdict` for the verdict order. `context` is the
898
+ * authentication context (§1.1) to resolve the actor's scopes under.
898
899
  */
899
900
  async traceRow(
900
901
  partition: string,
@@ -902,9 +903,10 @@ export class SyncularAdmin {
902
903
  readonly table: string;
903
904
  readonly rowId: string;
904
905
  readonly clientId: string;
906
+ readonly context?: string;
905
907
  },
906
908
  ): Promise<AdminRowTrace> {
907
- const { table, rowId, clientId } = query;
909
+ const { table, rowId, clientId, context } = query;
908
910
  const row = await this.inspectRow(partition, table, rowId, {
909
911
  historyLimit: 1,
910
912
  });
@@ -927,7 +929,7 @@ export class SyncularAdmin {
927
929
  if (record === undefined) {
928
930
  return { ...base, verdict: 'client-unknown', units: [] };
929
931
  }
930
- const allowed = await this.#allowedScopes(partition, record);
932
+ const allowed = await this.#allowedScopes(partition, record, context);
931
933
  return {
932
934
  ...base,
933
935
  client: (await this.#clientView(partition))(record),
@@ -945,12 +947,14 @@ export class SyncularAdmin {
945
947
 
946
948
  /**
947
949
  * Who has one row and who does not: the trace verdict for every known
948
- * client in the partition, resolving each actor's allowed scopes once.
950
+ * client in the partition, resolving each actor's allowed scopes once
951
+ * under `context` (§1.1).
949
952
  */
950
953
  async rowDelivery(
951
954
  partition: string,
952
955
  table: string,
953
956
  rowId: string,
957
+ context?: string,
954
958
  ): Promise<AdminRowDelivery> {
955
959
  const list = required(
956
960
  this.#storage.listClientRecords?.bind(this.#storage),
@@ -970,7 +974,7 @@ export class SyncularAdmin {
970
974
  if (!allowedByActor.has(record.actorId)) {
971
975
  allowedByActor.set(
972
976
  record.actorId,
973
- await this.#allowedScopes(partition, record),
977
+ await this.#allowedScopes(partition, record, context),
974
978
  );
975
979
  }
976
980
  clients.push({
@@ -1698,12 +1702,14 @@ export class SyncularAdmin {
1698
1702
  async #allowedScopes(
1699
1703
  partition: string,
1700
1704
  record: ClientRecord,
1705
+ context: string | undefined,
1701
1706
  ): Promise<ScopeMap | 'outage' | undefined> {
1702
1707
  if (this.#resolveScopes === undefined) return undefined;
1703
1708
  const resolved = await this.#resolveScopes({
1704
1709
  partition,
1705
1710
  actorId: record.actorId,
1706
1711
  clientId: record.clientId,
1712
+ ...(context !== undefined ? { context } : {}),
1707
1713
  });
1708
1714
  return resolved === RESOLVER_OUTAGE ? 'outage' : resolved;
1709
1715
  }
@@ -215,6 +215,7 @@ async function downloadBlob(
215
215
  const allowed = await ctx.resolveScopes({
216
216
  partition: ctx.partition,
217
217
  actorId: ctx.actorId,
218
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
218
219
  });
219
220
  // §7.3.3: leases never authorize a blob download — an outage denies.
220
221
  resolved =
@@ -267,6 +268,7 @@ async function downloadBlob(
267
268
  partition: ctx.partition,
268
269
  blobId,
269
270
  nowMs: clockOf(ctx)(),
271
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
270
272
  });
271
273
  return {
272
274
  headers: {
@@ -23,10 +23,11 @@
23
23
  * objects.
24
24
  *
25
25
  * {keyPrefix}find/{sha256Hex(canonical reuse key)}.json
26
- * Whole-table reuse pointer (§5.3): written only when
27
- * `rowCursor === null`, body = the record JSON. The reuse key is the
26
+ * Image reuse pointer (§5.3): written for every sqlite image and every
27
+ * first rows page, body = the record JSON. The reuse key is the
28
28
  * canonical JSON array `[partition, logEpoch, table, schemaVersion,
29
- * mediaType, scopeDigest, asOfCommitSeq]`, so `find` is one GET (plus a
29
+ * mediaType, scopeDigest, asOfCommitSeq]` plus the range start when it is
30
+ * not null, so `find` is one GET (plus a
30
31
  * HEAD to confirm the segment object itself still exists — lifecycle GC
31
32
  * may remove objects independently of pointers).
32
33
  *
@@ -319,6 +320,8 @@ export class BucketSegmentStore implements SegmentStore {
319
320
  key.mediaType,
320
321
  key.scopeDigest,
321
322
  key.asOfCommitSeq,
323
+ // A first range keeps the pointer key it had before range images.
324
+ ...(key.rowCursor === null ? [] : [key.rowCursor]),
322
325
  ]);
323
326
  return `${this.#prefix}find/${await sha256Hex(canonical)}.json`;
324
327
  }
@@ -425,7 +428,7 @@ export class BucketSegmentStore implements SegmentStore {
425
428
  sqliteSegments: metadata.mediaType === 'sqlite' ? 1 : 0,
426
429
  });
427
430
  }
428
- if (metadata.rowCursor === null) {
431
+ if (metadata.rowCursor === null || metadata.mediaType === 'sqlite') {
429
432
  await this.#bucket.put(await this.#findKeyFor(metadata), {
430
433
  body: new TextEncoder().encode(recordJson),
431
434
  contentType: 'application/json',
@@ -556,7 +559,7 @@ export class BucketSegmentStore implements SegmentStore {
556
559
  mediaType: key.mediaType,
557
560
  scopeDigest: key.scopeDigest,
558
561
  asOfCommitSeq: key.asOfCommitSeq,
559
- rowCursor: null,
562
+ rowCursor: key.rowCursor,
560
563
  nowMs,
561
564
  });
562
565
  if (publication === undefined) return undefined;
package/src/context.ts CHANGED
@@ -42,6 +42,12 @@ export interface ResolveScopesArgs {
42
42
  * actor + scopes only (§5.5, §5.9.5) and never consult a lease.
43
43
  */
44
44
  readonly clientId?: string;
45
+ /**
46
+ * The authentication context the host's `authenticate` returned for this
47
+ * request (§1.1), passed unchanged on every path that resolves scopes.
48
+ * Absent when the host returned none.
49
+ */
50
+ readonly context?: string;
45
51
  }
46
52
 
47
53
  /**
@@ -98,6 +104,12 @@ export interface ServerLimits {
98
104
  * pass it alone resets the units it reaches, which bootstrap instead.
99
105
  */
100
106
  readonly maxLiveSectionBytes: number;
107
+ /**
108
+ * §5.3 bound on one sqlite image's file size: the server cuts a table into
109
+ * range images in row order, each within this bound. A row larger than the
110
+ * bound gets an image of its own.
111
+ */
112
+ readonly maxImageSegmentBytes: number;
101
113
  }
102
114
 
103
115
  export const DEFAULT_LIMITS: ServerLimits = {
@@ -112,6 +124,8 @@ export const DEFAULT_LIMITS: ServerLimits = {
112
124
  maxWatchesPerSession: 100,
113
125
  // The live section is buffered whole before the first unit section.
114
126
  maxLiveSectionBytes: 16 * 1024 * 1024,
127
+ // §5.3 DECISION (2026-11-17): a client holds about three images at once.
128
+ maxImageSegmentBytes: 32 * 1024 * 1024,
115
129
  };
116
130
 
117
131
  /** Receives applied commits for realtime fanout (§8.2). */
@@ -253,6 +267,20 @@ export interface SyncServerConfig {
253
267
  export interface SyncRequestContext extends SyncServerConfig {
254
268
  readonly partition: string;
255
269
  readonly actorId: string;
270
+ /** The host authentication context (§1.1), at most 256 UTF-8 bytes. */
271
+ readonly context?: string;
272
+ }
273
+
274
+ /** §1.1: `authenticate` returned a context longer than 256 UTF-8 bytes. */
275
+ export class AuthContextTooLargeError extends Error {
276
+ override readonly name = 'AuthContextTooLargeError';
277
+ readonly code = 'sync.auth_context_too_large';
278
+ readonly details: { readonly byteLength: number; readonly max: 256 };
279
+
280
+ constructor(byteLength: number) {
281
+ super('authentication context exceeds 256 UTF-8 bytes');
282
+ this.details = { byteLength, max: 256 };
283
+ }
256
284
  }
257
285
 
258
286
  export function clockOf(ctx: SyncServerConfig): () => number {
@@ -275,10 +303,18 @@ export function limitsOf(ctx: SyncServerConfig): ServerLimits {
275
303
  return limits;
276
304
  }
277
305
 
278
- /** Refresh the registry after host authentication and return log continuity. */
279
- export function touchAuthenticatedPartition(
306
+ /**
307
+ * Refresh the registry after host authentication and return log continuity.
308
+ * Every authenticated entry point runs this first, so it also refuses an
309
+ * oversized authentication context (§1.1) before any resolver sees it.
310
+ */
311
+ export async function touchAuthenticatedPartition(
280
312
  ctx: SyncRequestContext,
281
313
  ): Promise<PartitionRegistryEntry> {
314
+ if (ctx.context !== undefined) {
315
+ const byteLength = new TextEncoder().encode(ctx.context).length;
316
+ if (byteLength > 256) throw new AuthContextTooLargeError(byteLength);
317
+ }
282
318
  return ctx.storage.touchPartition(
283
319
  ctx.partition,
284
320
  clockOf(ctx)(),
package/src/handler.ts CHANGED
@@ -159,7 +159,13 @@ async function authorizeFromLease(
159
159
  );
160
160
  }
161
161
  const lease = await leases.store.get(ctx.partition, clientId);
162
- if (lease === undefined || lease.actorId !== ctx.actorId) {
162
+ // A lease binds the actor and the authentication context it was issued
163
+ // under (§7.3.1): another session of the same actor is not its holder.
164
+ if (
165
+ lease === undefined ||
166
+ lease.actorId !== ctx.actorId ||
167
+ lease.context !== ctx.context
168
+ ) {
163
169
  throw syncError(
164
170
  'sync.auth_lease_required',
165
171
  'no valid auth lease for this client during an authorization outage (§7.3.3)',
@@ -192,6 +198,7 @@ async function resolveOnce(
192
198
  partition: ctx.partition,
193
199
  actorId: ctx.actorId,
194
200
  clientId,
201
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
195
202
  });
196
203
  } catch (error) {
197
204
  if (error instanceof SyncError) throw error;
@@ -231,6 +238,7 @@ async function resolveOnce(
231
238
  allowed,
232
239
  clockOf(ctx)(),
233
240
  ctx.leases.ttlMs,
241
+ ctx.context,
234
242
  );
235
243
  }
236
244
  return { resolved: { ok: true, allowed }, leaseToEmit };
package/src/index.ts CHANGED
@@ -85,6 +85,7 @@ export * from './sqlite-driver';
85
85
  export {
86
86
  IMAGE_METADATA_TABLE,
87
87
  IMAGE_VERSION_COLUMN,
88
+ type SqliteImage,
88
89
  type SqliteImageBuilder,
89
90
  type SqliteImageInput,
90
91
  writeSqliteImage,
Binary file
package/src/operations.ts CHANGED
@@ -379,6 +379,7 @@ export function registerRemoteQuery<Params>(
379
379
  partition: ctx.partition,
380
380
  actorId: ctx.actorId,
381
381
  clientId,
382
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
382
383
  });
383
384
  if (allowed === RESOLVER_OUTAGE) {
384
385
  throw syncError(
@@ -719,6 +720,7 @@ export function registerRemoteCommand<Input>(
719
720
  partition: ctx.partition,
720
721
  actorId: ctx.actorId,
721
722
  clientId,
723
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
722
724
  });
723
725
  if (allowed === RESOLVER_OUTAGE) {
724
726
  throw syncError(