@syncular/server 0.91.0 → 0.92.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/context.d.ts CHANGED
@@ -15,7 +15,7 @@ import type { ServerSchema, CompiledSchema } from './schema.js';
15
15
  import type { SegmentStore } from './segment-store.js';
16
16
  import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlConfig } from './signed-url.js';
17
17
  import type { SqliteImageBuilder } from './sqlite-image.js';
18
- import type { CheckpointDeclaration, PartitionRegistryEntry, ServerStorage, StoredCommit } from './storage.js';
18
+ import type { CheckpointDeclaration, PartitionTouch, ServerStorage, StoredCommit } from './storage.js';
19
19
  import type { CommitValidator, ValidatorRegistry } from './validate.js';
20
20
  /** SSP2 body content type (§1.1). */
21
21
  export declare const SSP2_CONTENT_TYPE = "application/vnd.syncular.sync.v2";
@@ -36,6 +36,16 @@ export interface ResolveScopesArgs {
36
36
  * Absent when the host returned none.
37
37
  */
38
38
  readonly context?: string;
39
+ /** Present on a direct segment download (§5.5) only. */
40
+ readonly phase?: 'segment-download';
41
+ /**
42
+ * The download's `X-Syncular-Scopes` map, present with `phase`. The
43
+ * resolver MAY answer for these values only (§3.2 step 3): `'*'` for a
44
+ * requested variable exactly when the full answer holds it, otherwise the
45
+ * requested values the actor holds; an answer that grants `'*'` carries
46
+ * every other variable in full.
47
+ */
48
+ readonly requested?: ScopeMap;
39
49
  }
40
50
  /**
41
51
  * Sentinel a resolver returns to signal a **live-authorization outage**
@@ -253,4 +263,4 @@ export declare function limitsOf(ctx: SyncServerConfig): ServerLimits;
253
263
  * Every authenticated entry point runs this first, so it also refuses an
254
264
  * oversized authentication context (§1.1) before any resolver sees it.
255
265
  */
256
- export declare function touchAuthenticatedPartition(ctx: SyncRequestContext): Promise<PartitionRegistryEntry>;
266
+ export declare function touchAuthenticatedPartition(ctx: SyncRequestContext): Promise<PartitionTouch>;
@@ -37,6 +37,7 @@ export declare class D1ServerStorage extends SqliteFamilyStorage implements Serv
37
37
  * binds one per app column plus the five `_sync_*` meta columns.
38
38
  */
39
39
  protected readonly maxBindParams = 100;
40
+ protected readonly checkpointSchemaVersionSql = "NULL";
40
41
  constructor(db: D1Database, options?: D1ServerStorageOptions);
41
42
  protected all<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
42
43
  /** Queue one read into the current turn's `db.batch` (see `#pendingReads`). */
@@ -554,6 +554,8 @@ export class D1ServerStorage extends SqliteFamilyStorage {
554
554
  * binds one per app column plus the five `_sync_*` meta columns.
555
555
  */
556
556
  maxBindParams = 100;
557
+ // D1 declares no backfill checkpoints (see `readCheckpoints`).
558
+ checkpointSchemaVersionSql = 'NULL';
557
559
  /**
558
560
  * Page reads waiting for the end of the current microtask turn. A pull
559
561
  * starts the first snapshot page and scope pin of every bootstrapping unit
package/dist/handler.js CHANGED
@@ -136,7 +136,12 @@ async function planRequest(request, ctx, schema, registry) {
136
136
  if (header.logEpoch === undefined && pushes.length > 0) {
137
137
  throw syncError('sync.invalid_request', 'epoch acquisition requests must not carry push commits (§2.1)');
138
138
  }
139
- const epochReset = header.logEpoch !== registry.logEpoch;
139
+ const adopt = request.frames.some((frame) => frame.type === 'ADOPT_EPOCH');
140
+ if (adopt && header.logEpoch !== undefined) {
141
+ throw syncError('sync.invalid_request', 'epoch adoption requests must not carry logEpoch (§2.1)');
142
+ }
143
+ // §2.1: adoption serves the request under the current epoch.
144
+ const epochReset = !adopt && header.logEpoch !== registry.logEpoch;
140
145
  const unserved = {
141
146
  wireVersion: request.wireVersion,
142
147
  logEpoch: registry.logEpoch,
@@ -39,7 +39,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
39
39
  import { type UnitScopes } from '@syncular/core';
40
40
  import { type PgExecutor } from './pg-executor.js';
41
41
  import type { CompiledSchema, CompiledTable } from './schema.js';
42
- import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, IndexRowScanQuery, LiveWindow, LiveWindowQuery, PartitionRegistryEntry, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
42
+ import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, IndexRowScanQuery, LiveWindow, LiveWindowQuery, PartitionRegistryEntry, PartitionTouch, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
43
43
  /**
44
44
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
45
45
  *
@@ -89,7 +89,7 @@ export declare class PostgresServerStorage implements ServerStorage {
89
89
  /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
90
90
  table(name: string): CompiledTable;
91
91
  ensureSchema(schema: CompiledSchema, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
92
- touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
92
+ touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionTouch>;
93
93
  rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
94
94
  listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
95
95
  /**
@@ -1786,7 +1786,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
1786
1786
  if (initialLogEpoch.length === 0) {
1787
1787
  throw new Error('initial log epoch must be non-empty');
1788
1788
  }
1789
- let row = (await this.#exec.query(`SELECT log_epoch, epoch_required, last_authenticated_at_ms
1789
+ const checkpointVersion = `(SELECT max(schema_version)
1790
+ FROM sync_backfill_checkpoints WHERE partition=$1)
1791
+ AS checkpoint_schema_version`;
1792
+ let row = (await this.#exec.query(`SELECT log_epoch, epoch_required, last_authenticated_at_ms,
1793
+ ${checkpointVersion}
1790
1794
  FROM sync_partition_registry WHERE partition=$1`, [partition])).rows[0];
1791
1795
  if (row === undefined ||
1792
1796
  authenticatedAtMs - asNumber(row.last_authenticated_at_ms) >=
@@ -1796,7 +1800,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
1796
1800
  ) VALUES ($1,$2,$3)
1797
1801
  ON CONFLICT(partition) DO UPDATE SET
1798
1802
  last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms
1799
- RETURNING log_epoch, epoch_required, last_authenticated_at_ms`, [partition, initialLogEpoch, authenticatedAtMs])).rows[0];
1803
+ RETURNING log_epoch, epoch_required, last_authenticated_at_ms,
1804
+ ${checkpointVersion}`, [partition, initialLogEpoch, authenticatedAtMs])).rows[0];
1800
1805
  }
1801
1806
  if (row === undefined)
1802
1807
  throw new Error('partition registry write did not persist');
@@ -1805,6 +1810,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
1805
1810
  logEpoch: row.log_epoch,
1806
1811
  epochRequired: row.epoch_required,
1807
1812
  lastAuthenticatedAtMs: asNumber(row.last_authenticated_at_ms),
1813
+ checkpointSchemaVersion: row.checkpoint_schema_version ?? undefined,
1808
1814
  };
1809
1815
  }
1810
1816
  async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
@@ -83,7 +83,7 @@ async function downloadSegment(ctx, request) {
83
83
  if (entry === undefined) {
84
84
  throw syncError('sync.not_found', 'unknown segment (§5.5)');
85
85
  }
86
- const record = await authorizePublication(ctx, request, registry.logEpoch, entry.record);
86
+ const record = await authorizePublication(ctx, request, registry, entry.record);
87
87
  return { record, bytes: entry.bytes, headers: segmentHeaders(record) };
88
88
  }
89
89
  async function openSegment(ctx, request) {
@@ -102,7 +102,7 @@ async function openSegment(ctx, request) {
102
102
  }
103
103
  let record;
104
104
  try {
105
- record = await authorizePublication(ctx, request, registry.logEpoch, opened.record);
105
+ record = await authorizePublication(ctx, request, registry, opened.record);
106
106
  }
107
107
  catch (error) {
108
108
  await opened.body.cancel();
@@ -128,7 +128,7 @@ function segmentHeaders(record) {
128
128
  * Select and authorize the caller's publication of a stored segment
129
129
  * (§5.5), projected onto that publication.
130
130
  */
131
- async function authorizePublication(ctx, request, logEpoch, stored) {
131
+ async function authorizePublication(ctx, request, { logEpoch, checkpointSchemaVersion }, stored) {
132
132
  // Select the caller's own publication context. A publication under a
133
133
  // different partition or a stale log epoch is not this caller's grant, and
134
134
  // the entry's existence must not leak across that boundary (§5.5).
@@ -144,6 +144,8 @@ async function authorizePublication(ctx, request, logEpoch, stored) {
144
144
  partition: ctx.partition,
145
145
  actorId: ctx.actorId,
146
146
  ...(ctx.context !== undefined ? { context: ctx.context } : {}),
147
+ phase: 'segment-download',
148
+ requested,
147
149
  });
148
150
  // §7.3.3: leases authorize sync rounds, never downloads — an outage
149
151
  // signal here denies (re-authorization needs live scopes, §5.5).
@@ -218,9 +220,10 @@ async function authorizePublication(ctx, request, logEpoch, stored) {
218
220
  // RFC 0007: a descriptor minted before this partition declared a backfill
219
221
  // checkpoint is not a complete window once the projection becomes
220
222
  // checkpointed. SPEC §9 mints segments per schema version, so refuse and
221
- // let the client re-pull for a fresh descriptor.
222
- const checkpoints = await ctx.storage.readCheckpoints(ctx.partition);
223
- if (checkpoints.some((checkpoint) => checkpoint.schemaVersion > publication.schemaVersion)) {
223
+ // let the client re-pull for a fresh descriptor. `touchPartition` read the
224
+ // highest checkpoint version in its registry statement.
225
+ if (checkpointSchemaVersion !== undefined &&
226
+ checkpointSchemaVersion > publication.schemaVersion) {
224
227
  throw syncError('sync.segment_expired', 'segment predates the partition backfill checkpoint — re-pull (§5.1)');
225
228
  }
226
229
  // The returned record is projected onto the selected publication, so its
@@ -18,7 +18,7 @@ import type { UnitScopes } from '@syncular/core';
18
18
  import { type BoundAuthoritativeQuery } from './authoritative-query.js';
19
19
  import type { CompiledTable } from './schema.js';
20
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, StoredPushResult, StoredReaction, StoredRow, Tombstone } from './storage.js';
21
+ import type { AuthoritativeQueryRequest, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitPruneQuery, CommitPruneResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, NewCommit, OutboxSequence, OutboxSettlement, NewReaction, PartitionRegistryEntry, PartitionTouch, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, StoredPushResult, StoredReaction, StoredRow, Tombstone } from './storage.js';
22
22
  /**
23
23
  * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
24
24
  * the whole string via `db.exec(SQLITE_DDL)`; D1 applies each statement
@@ -98,6 +98,12 @@ export declare abstract class SqliteFamilyStorage {
98
98
  protected schemaVersion: number | undefined;
99
99
  /** Bound parameters one statement accepts. */
100
100
  protected abstract readonly maxBindParams: number;
101
+ /**
102
+ * `touchPartition`'s SQL for the partition's highest declared backfill
103
+ * checkpoint version, reading the partition as `?1`, or `NULL` on a storage
104
+ * that declares no checkpoints.
105
+ */
106
+ protected abstract readonly checkpointSchemaVersionSql: string;
101
107
  /** `chooseScanVariable` picks, shared with this storage's transactions. */
102
108
  protected readonly scanVariables: Map<string, string>;
103
109
  /** Run one statement and return its rows. */
@@ -113,7 +119,7 @@ export declare abstract class SqliteFamilyStorage {
113
119
  /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
114
120
  table(name: string): CompiledTable;
115
121
  protected prepareAuthoritativeQuery(partition: string, query: AuthoritativeQueryRequest): BoundAuthoritativeQuery;
116
- touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
122
+ touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionTouch>;
117
123
  rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
118
124
  listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
119
125
  getMaxCommitSeq(partition: string): Promise<number>;
@@ -302,15 +302,19 @@ export class SqliteFamilyStorage {
302
302
  ],
303
303
  },
304
304
  {
305
- sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
306
- FROM sync_partition_registry WHERE partition=?`,
305
+ sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms,
306
+ ${this.checkpointSchemaVersionSql} AS checkpoint_schema_version
307
+ FROM sync_partition_registry WHERE partition=?1`,
307
308
  params: [partition],
308
309
  },
309
310
  ]);
310
311
  const row = rows?.[0];
311
312
  if (row === undefined)
312
313
  throw new Error('partition registry write did not persist');
313
- return toPartitionRegistryEntry(row);
314
+ return {
315
+ ...toPartitionRegistryEntry(row),
316
+ checkpointSchemaVersion: row.checkpoint_schema_version ?? undefined,
317
+ };
314
318
  }
315
319
  async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
316
320
  if (logEpoch.length === 0)
@@ -6,6 +6,7 @@ export declare class SqliteServerStorage extends SqliteFamilyStorage implements
6
6
  #private;
7
7
  readonly db: SqliteDatabase;
8
8
  protected readonly maxBindParams: number;
9
+ protected readonly checkpointSchemaVersionSql = "(SELECT max(schema_version) FROM sync_backfill_checkpoints WHERE partition=?1)";
9
10
  constructor(db?: SqliteDatabase | string);
10
11
  protected all<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
11
12
  protected guardedAll<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
@@ -191,6 +191,7 @@ class SqliteTransaction extends SqliteFamilyTransaction {
191
191
  export class SqliteServerStorage extends SqliteFamilyStorage {
192
192
  db;
193
193
  maxBindParams = Number.POSITIVE_INFINITY;
194
+ checkpointSchemaVersionSql = '(SELECT max(schema_version) FROM sync_backfill_checkpoints WHERE partition=?1)';
194
195
  /**
195
196
  * §6.4: one SQLite connection serves one caller at a time. A transaction
196
197
  * holds it from `begin` until commit or rollback; every other call waits
package/dist/storage.d.ts CHANGED
@@ -529,6 +529,15 @@ export interface PartitionRegistryEntry {
529
529
  readonly epochRequired: boolean;
530
530
  readonly lastAuthenticatedAtMs: number;
531
531
  }
532
+ /** `touchPartition`: the registry entry, read in the same statement as the checkpoints. */
533
+ export interface PartitionTouch extends PartitionRegistryEntry {
534
+ /**
535
+ * RFC 0007: the highest `schemaVersion` among the partition's declared
536
+ * backfill checkpoints, `undefined` when it declares none. A segment
537
+ * download refuses a publication older than it (§5.5).
538
+ */
539
+ readonly checkpointSchemaVersion: number | undefined;
540
+ }
532
541
  /**
533
542
  * Commit-log metadata (no change payloads) for the admin/console read
534
543
  * surface. `changeCount` is the number of changes the commit carries;
@@ -831,7 +840,7 @@ export interface ServerStorage {
831
840
  * {@link PARTITION_TOUCH_INTERVAL_MS} behind `authenticatedAtMs` is read
832
841
  * back without a write, so a request that only reads takes no write lock.
833
842
  */
834
- touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
843
+ touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionTouch>;
835
844
  /**
836
845
  * Rotate log continuity after restore and delete the partition's client
837
846
  * records. Watermark rows stay (§6.3.2).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server",
3
- "version": "0.91.0",
3
+ "version": "0.92.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.91.0"
71
+ "@syncular/core": "0.92.0"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@electric-sql/pglite": "^0.5.4"
package/src/context.ts CHANGED
@@ -21,7 +21,7 @@ import type {
21
21
  import type { SqliteImageBuilder } from './sqlite-image';
22
22
  import type {
23
23
  CheckpointDeclaration,
24
- PartitionRegistryEntry,
24
+ PartitionTouch,
25
25
  ServerStorage,
26
26
  StoredCommit,
27
27
  } from './storage';
@@ -48,6 +48,16 @@ export interface ResolveScopesArgs {
48
48
  * Absent when the host returned none.
49
49
  */
50
50
  readonly context?: string;
51
+ /** Present on a direct segment download (§5.5) only. */
52
+ readonly phase?: 'segment-download';
53
+ /**
54
+ * The download's `X-Syncular-Scopes` map, present with `phase`. The
55
+ * resolver MAY answer for these values only (§3.2 step 3): `'*'` for a
56
+ * requested variable exactly when the full answer holds it, otherwise the
57
+ * requested values the actor holds; an answer that grants `'*'` carries
58
+ * every other variable in full.
59
+ */
60
+ readonly requested?: ScopeMap;
51
61
  }
52
62
 
53
63
  /**
@@ -310,7 +320,7 @@ export function limitsOf(ctx: SyncServerConfig): ServerLimits {
310
320
  */
311
321
  export async function touchAuthenticatedPartition(
312
322
  ctx: SyncRequestContext,
313
- ): Promise<PartitionRegistryEntry> {
323
+ ): Promise<PartitionTouch> {
314
324
  if (ctx.context !== undefined) {
315
325
  const byteLength = new TextEncoder().encode(ctx.context).length;
316
326
  if (byteLength > 256) throw new AuthContextTooLargeError(byteLength);
package/src/d1-storage.ts CHANGED
@@ -906,6 +906,8 @@ export class D1ServerStorage
906
906
  * binds one per app column plus the five `_sync_*` meta columns.
907
907
  */
908
908
  protected readonly maxBindParams = 100;
909
+ // D1 declares no backfill checkpoints (see `readCheckpoints`).
910
+ protected readonly checkpointSchemaVersionSql = 'NULL';
909
911
  /**
910
912
  * Page reads waiting for the end of the current microtask turn. A pull
911
913
  * starts the first snapshot page and scope pin of every bootstrapping unit
package/src/handler.ts CHANGED
@@ -280,7 +280,15 @@ async function planRequest(
280
280
  'epoch acquisition requests must not carry push commits (§2.1)',
281
281
  );
282
282
  }
283
- const epochReset = header.logEpoch !== registry.logEpoch;
283
+ const adopt = request.frames.some((frame) => frame.type === 'ADOPT_EPOCH');
284
+ if (adopt && header.logEpoch !== undefined) {
285
+ throw syncError(
286
+ 'sync.invalid_request',
287
+ 'epoch adoption requests must not carry logEpoch (§2.1)',
288
+ );
289
+ }
290
+ // §2.1: adoption serves the request under the current epoch.
291
+ const epochReset = !adopt && header.logEpoch !== registry.logEpoch;
284
292
  const unserved = {
285
293
  wireVersion: request.wireVersion,
286
294
  logEpoch: registry.logEpoch,
@@ -137,6 +137,7 @@ import type {
137
137
  OutboxSequence,
138
138
  OutboxSettlement,
139
139
  PartitionRegistryEntry,
140
+ PartitionTouch,
140
141
  PreparedPushApply,
141
142
  PushApplyOptions,
142
143
  PrunedReactionCounts,
@@ -2567,7 +2568,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2567
2568
  partition: string,
2568
2569
  authenticatedAtMs: number,
2569
2570
  initialLogEpoch: string,
2570
- ): Promise<PartitionRegistryEntry> {
2571
+ ): Promise<PartitionTouch> {
2571
2572
  if (initialLogEpoch.length === 0) {
2572
2573
  throw new Error('initial log epoch must be non-empty');
2573
2574
  }
@@ -2575,10 +2576,15 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2575
2576
  log_epoch: string;
2576
2577
  epoch_required: boolean;
2577
2578
  last_authenticated_at_ms: unknown;
2579
+ checkpoint_schema_version: number | null;
2578
2580
  };
2581
+ const checkpointVersion = `(SELECT max(schema_version)
2582
+ FROM sync_backfill_checkpoints WHERE partition=$1)
2583
+ AS checkpoint_schema_version`;
2579
2584
  let row = (
2580
2585
  await this.#exec.query<Registry>(
2581
- `SELECT log_epoch, epoch_required, last_authenticated_at_ms
2586
+ `SELECT log_epoch, epoch_required, last_authenticated_at_ms,
2587
+ ${checkpointVersion}
2582
2588
  FROM sync_partition_registry WHERE partition=$1`,
2583
2589
  [partition],
2584
2590
  )
@@ -2595,7 +2601,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2595
2601
  ) VALUES ($1,$2,$3)
2596
2602
  ON CONFLICT(partition) DO UPDATE SET
2597
2603
  last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms
2598
- RETURNING log_epoch, epoch_required, last_authenticated_at_ms`,
2604
+ RETURNING log_epoch, epoch_required, last_authenticated_at_ms,
2605
+ ${checkpointVersion}`,
2599
2606
  [partition, initialLogEpoch, authenticatedAtMs],
2600
2607
  )
2601
2608
  ).rows[0];
@@ -2607,6 +2614,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2607
2614
  logEpoch: row.log_epoch,
2608
2615
  epochRequired: row.epoch_required,
2609
2616
  lastAuthenticatedAtMs: asNumber(row.last_authenticated_at_ms),
2617
+ checkpointSchemaVersion: row.checkpoint_schema_version ?? undefined,
2610
2618
  };
2611
2619
  }
2612
2620
 
@@ -25,6 +25,7 @@ import {
25
25
  publicationRecord,
26
26
  type SegmentRecord,
27
27
  } from './segment-store';
28
+ import type { PartitionTouch } from './storage';
28
29
 
29
30
  export interface SegmentDownloadRequest {
30
31
  readonly segmentId: string;
@@ -164,7 +165,7 @@ async function downloadSegment(
164
165
  const record = await authorizePublication(
165
166
  ctx,
166
167
  request,
167
- registry.logEpoch,
168
+ registry,
168
169
  entry.record,
169
170
  );
170
171
  return { record, bytes: entry.bytes, headers: segmentHeaders(record) };
@@ -192,12 +193,7 @@ async function openSegment(
192
193
  }
193
194
  let record: SegmentRecord;
194
195
  try {
195
- record = await authorizePublication(
196
- ctx,
197
- request,
198
- registry.logEpoch,
199
- opened.record,
200
- );
196
+ record = await authorizePublication(ctx, request, registry, opened.record);
201
197
  } catch (error) {
202
198
  await opened.body.cancel();
203
199
  throw error;
@@ -227,7 +223,7 @@ function segmentHeaders(record: SegmentRecord): Record<string, string> {
227
223
  async function authorizePublication(
228
224
  ctx: SyncRequestContext,
229
225
  request: SegmentDownloadRequest,
230
- logEpoch: string,
226
+ { logEpoch, checkpointSchemaVersion }: PartitionTouch,
231
227
  stored: SegmentRecord,
232
228
  ): Promise<SegmentRecord> {
233
229
  // Select the caller's own publication context. A publication under a
@@ -250,6 +246,8 @@ async function authorizePublication(
250
246
  partition: ctx.partition,
251
247
  actorId: ctx.actorId,
252
248
  ...(ctx.context !== undefined ? { context: ctx.context } : {}),
249
+ phase: 'segment-download',
250
+ requested,
253
251
  });
254
252
  // §7.3.3: leases authorize sync rounds, never downloads — an outage
255
253
  // signal here denies (re-authorization needs live scopes, §5.5).
@@ -348,12 +346,11 @@ async function authorizePublication(
348
346
  // RFC 0007: a descriptor minted before this partition declared a backfill
349
347
  // checkpoint is not a complete window once the projection becomes
350
348
  // checkpointed. SPEC §9 mints segments per schema version, so refuse and
351
- // let the client re-pull for a fresh descriptor.
352
- const checkpoints = await ctx.storage.readCheckpoints(ctx.partition);
349
+ // let the client re-pull for a fresh descriptor. `touchPartition` read the
350
+ // highest checkpoint version in its registry statement.
353
351
  if (
354
- checkpoints.some(
355
- (checkpoint) => checkpoint.schemaVersion > publication.schemaVersion,
356
- )
352
+ checkpointSchemaVersion !== undefined &&
353
+ checkpointSchemaVersion > publication.schemaVersion
357
354
  ) {
358
355
  throw syncError(
359
356
  'sync.segment_expired',
@@ -79,6 +79,7 @@ import type {
79
79
  OutboxSettlement,
80
80
  NewReaction,
81
81
  PartitionRegistryEntry,
82
+ PartitionTouch,
82
83
  PrunedReactionCounts,
83
84
  PushWatermark,
84
85
  ReactionClaimQuery,
@@ -433,6 +434,12 @@ export abstract class SqliteFamilyStorage {
433
434
  protected schemaVersion: number | undefined;
434
435
  /** Bound parameters one statement accepts. */
435
436
  protected abstract readonly maxBindParams: number;
437
+ /**
438
+ * `touchPartition`'s SQL for the partition's highest declared backfill
439
+ * checkpoint version, reading the partition as `?1`, or `NULL` on a storage
440
+ * that declares no checkpoints.
441
+ */
442
+ protected abstract readonly checkpointSchemaVersionSql: string;
436
443
  /** `chooseScanVariable` picks, shared with this storage's transactions. */
437
444
  protected readonly scanVariables = new Map<string, string>();
438
445
 
@@ -492,7 +499,7 @@ export abstract class SqliteFamilyStorage {
492
499
  partition: string,
493
500
  authenticatedAtMs: number,
494
501
  initialLogEpoch: string,
495
- ): Promise<PartitionRegistryEntry> {
502
+ ): Promise<PartitionTouch> {
496
503
  if (initialLogEpoch.length === 0) {
497
504
  throw new Error('initial log epoch must be non-empty');
498
505
  }
@@ -515,15 +522,23 @@ export abstract class SqliteFamilyStorage {
515
522
  ],
516
523
  },
517
524
  {
518
- sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
519
- FROM sync_partition_registry WHERE partition=?`,
525
+ sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms,
526
+ ${this.checkpointSchemaVersionSql} AS checkpoint_schema_version
527
+ FROM sync_partition_registry WHERE partition=?1`,
520
528
  params: [partition],
521
529
  },
522
530
  ]);
523
- const row = rows?.[0] as SqlitePartitionRegistryRecord | undefined;
531
+ const row = rows?.[0] as
532
+ | (SqlitePartitionRegistryRecord & {
533
+ checkpoint_schema_version: number | null;
534
+ })
535
+ | undefined;
524
536
  if (row === undefined)
525
537
  throw new Error('partition registry write did not persist');
526
- return toPartitionRegistryEntry(row);
538
+ return {
539
+ ...toPartitionRegistryEntry(row),
540
+ checkpointSchemaVersion: row.checkpoint_schema_version ?? undefined,
541
+ };
527
542
  }
528
543
 
529
544
  async rotatePartitionLogEpoch(
@@ -341,6 +341,8 @@ export class SqliteServerStorage
341
341
  {
342
342
  readonly db: SqliteDatabase;
343
343
  protected readonly maxBindParams = Number.POSITIVE_INFINITY;
344
+ protected readonly checkpointSchemaVersionSql =
345
+ '(SELECT max(schema_version) FROM sync_backfill_checkpoints WHERE partition=?1)';
344
346
  /**
345
347
  * §6.4: one SQLite connection serves one caller at a time. A transaction
346
348
  * holds it from `begin` until commit or rollback; every other call waits
package/src/storage.ts CHANGED
@@ -889,6 +889,16 @@ export interface PartitionRegistryEntry {
889
889
  readonly lastAuthenticatedAtMs: number;
890
890
  }
891
891
 
892
+ /** `touchPartition`: the registry entry, read in the same statement as the checkpoints. */
893
+ export interface PartitionTouch extends PartitionRegistryEntry {
894
+ /**
895
+ * RFC 0007: the highest `schemaVersion` among the partition's declared
896
+ * backfill checkpoints, `undefined` when it declares none. A segment
897
+ * download refuses a publication older than it (§5.5).
898
+ */
899
+ readonly checkpointSchemaVersion: number | undefined;
900
+ }
901
+
892
902
  /**
893
903
  * Commit-log metadata (no change payloads) for the admin/console read
894
904
  * surface. `changeCount` is the number of changes the commit carries;
@@ -1270,7 +1280,7 @@ export interface ServerStorage {
1270
1280
  partition: string,
1271
1281
  authenticatedAtMs: number,
1272
1282
  initialLogEpoch: string,
1273
- ): Promise<PartitionRegistryEntry>;
1283
+ ): Promise<PartitionTouch>;
1274
1284
  /**
1275
1285
  * Rotate log continuity after restore and delete the partition's client
1276
1286
  * records. Watermark rows stay (§6.3.2).