@syncular/client 0.59.0 → 0.60.1

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 (66) hide show
  1. package/README.md +27 -27
  2. package/dist/apply.d.ts +6 -5
  3. package/dist/apply.js +52 -25
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +4 -4
  6. package/dist/bun-database.js +3 -16
  7. package/dist/client.d.ts +57 -66
  8. package/dist/client.js +701 -796
  9. package/dist/devtools.d.ts +2 -2
  10. package/dist/devtools.js +3 -3
  11. package/dist/diagnostics.d.ts +17 -28
  12. package/dist/diagnostics.js +1 -2
  13. package/dist/errors.d.ts +1 -1
  14. package/dist/errors.js +1 -1
  15. package/dist/failed-overlay.js +4 -1
  16. package/dist/http.js +19 -5
  17. package/dist/invalidation.d.ts +3 -4
  18. package/dist/invalidation.js +9 -22
  19. package/dist/native-bridge.d.ts +7 -16
  20. package/dist/native-bridge.js +16 -41
  21. package/dist/node-database.js +16 -25
  22. package/dist/outbox.js +1 -0
  23. package/dist/progress.d.ts +2 -2
  24. package/dist/query-guard.d.ts +15 -6
  25. package/dist/query-guard.js +38 -6
  26. package/dist/reactive-store.js +2 -2
  27. package/dist/remote.js +9 -9
  28. package/dist/schema.d.ts +3 -2
  29. package/dist/schema.js +28 -12
  30. package/dist/state.d.ts +69 -36
  31. package/dist/state.js +178 -89
  32. package/dist/sync-scheduler.js +2 -2
  33. package/dist/transport.d.ts +2 -2
  34. package/dist/window.d.ts +30 -52
  35. package/dist/window.js +33 -77
  36. package/dist/worker-core.js +6 -6
  37. package/dist/worker-host.d.ts +9 -8
  38. package/dist/worker-host.js +23 -14
  39. package/dist/worker-protocol.d.ts +9 -8
  40. package/package.json +3 -3
  41. package/src/apply.ts +87 -33
  42. package/src/authority.ts +31 -17
  43. package/src/blob.ts +4 -3
  44. package/src/bun-database.ts +9 -14
  45. package/src/client.ts +886 -1037
  46. package/src/devtools.ts +5 -5
  47. package/src/diagnostics.ts +17 -37
  48. package/src/errors.ts +1 -1
  49. package/src/failed-overlay.ts +6 -1
  50. package/src/http.ts +22 -9
  51. package/src/invalidation.ts +9 -29
  52. package/src/native-bridge.ts +22 -58
  53. package/src/node-database.ts +26 -27
  54. package/src/outbox.ts +1 -0
  55. package/src/progress.ts +2 -2
  56. package/src/query-guard.ts +45 -8
  57. package/src/reactive-store.ts +2 -2
  58. package/src/remote.ts +12 -16
  59. package/src/schema.ts +48 -13
  60. package/src/state.ts +246 -125
  61. package/src/sync-scheduler.ts +2 -2
  62. package/src/transport.ts +2 -2
  63. package/src/window.ts +55 -134
  64. package/src/worker-core.ts +6 -6
  65. package/src/worker-host.ts +27 -19
  66. package/src/worker-protocol.ts +8 -8
package/dist/state.js CHANGED
@@ -1,72 +1,163 @@
1
1
  export const META_TABLE = '_syncular_meta';
2
2
  import { PENDING_EVICTIONS } from './window.js';
3
3
  import { WINDOWS_TABLE } from './window.js';
4
- export const SUBSCRIPTIONS_TABLE = '_syncular_subscriptions';
4
+ export const UNITS_TABLE = '_syncular_units';
5
5
  import { ClientSyncError } from './errors.js';
6
6
  export const LOCAL_REVISION_KEY = 'localRevision';
7
+ /** §4.5 replica cursor; absent means `-1`. */
8
+ export const REPLICA_CURSOR_KEY = 'replicaCursor';
9
+ /** Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty. */
10
+ export const ECHO_DIGEST_KEY = 'echoDigest';
11
+ /** Hex of the registration digest of the list the server stores (§4.1). */
12
+ export const REGISTERED_DIGEST_KEY = 'registrationDigest';
7
13
  const MAX_U64 = 18446744073709551615n;
14
+ /** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
15
+ export function bootstrapping(unit) {
16
+ return (unit.cursor !== undefined &&
17
+ (unit.cursor < 0 || unit.bootstrapState !== undefined));
18
+ }
19
+ /** §3.3 row ownership: active, live or post-bootstrap, with an echo. */
20
+ export function owning(unit) {
21
+ return (unit.status === 'active' && unit.echo !== undefined && !bootstrapping(unit));
22
+ }
23
+ /** §4.1: the unit covers every table declaring all of its variables. */
24
+ export function covers(table, scopes) {
25
+ return Object.keys(scopes).every((variable) => table.scopeColumnByVariable.has(variable));
26
+ }
27
+ /**
28
+ * §4.4: the effective scopes of the (unit, table) pair under `echo`: the
29
+ * scope map as one-element lists plus the fenced lists. Undefined when the
30
+ * fence revoked the pair.
31
+ */
32
+ export function pairScopes(scopes, table, echo) {
33
+ const fenced = echo?.find((record) => record.table === table);
34
+ if (fenced?.status === 'revoked')
35
+ return undefined;
36
+ const effective = { ...fenced?.scopes };
37
+ for (const [variable, value] of Object.entries(scopes))
38
+ effective[variable] = [value];
39
+ return effective;
40
+ }
41
+ /** §3.3 row ownership: the pair scopes of every owner of `table` but one.
42
+ * A bootstrapping unit owns the tables its current bootstrap seeded. */
43
+ export function unitOwners(units, table, exceptId) {
44
+ return units.flatMap((unit) => {
45
+ const scopes = unit.id !== exceptId &&
46
+ (owning(unit) ||
47
+ (unit.status === 'active' &&
48
+ unit.echo !== undefined &&
49
+ unit.seeded.includes(table.name))) &&
50
+ covers(table, unit.scopes)
51
+ ? pairScopes(unit.scopes, table.name, unit.echo)
52
+ : undefined;
53
+ return scopes === undefined ? [] : [scopes];
54
+ });
55
+ }
56
+ /** A unit row; every persisted field must have its stored type and shape,
57
+ * otherwise the row is `sync.local_corrupt` (§7.5). */
8
58
  function rowToRecord(row) {
9
- return {
10
- id: row.id,
11
- table: row.tbl,
12
- scopes: JSON.parse(row.requested_scopes),
13
- ...(row.params !== null ? { params: row.params } : {}),
14
- cursor: row.cursor,
15
- ...(row.bootstrap_state !== null
16
- ? { bootstrapState: row.bootstrap_state }
17
- : {}),
18
- ...(row.effective_scopes !== null
19
- ? {
20
- effectiveScopes: JSON.parse(row.effective_scopes),
21
- }
22
- : {}),
23
- status: row.status,
24
- ...(row.reason_code !== null
25
- ? { reasonCode: row.reason_code }
26
- : {}),
59
+ const corrupt = () => new ClientSyncError('sync.local_corrupt', 'persisted unit state is invalid');
60
+ const json = (raw) => {
61
+ if (typeof raw !== 'string')
62
+ throw corrupt();
63
+ try {
64
+ return JSON.parse(raw);
65
+ }
66
+ catch {
67
+ throw corrupt();
68
+ }
69
+ };
70
+ const isMap = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
71
+ const isStrings = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
72
+ const optionalText = (value) => {
73
+ if (value !== null && typeof value !== 'string')
74
+ throw corrupt();
75
+ return value ?? undefined;
76
+ };
77
+ const scopes = json(row.scopes);
78
+ const seeded = json(row.seeded);
79
+ const echo = row.echo === null ? undefined : json(row.echo);
80
+ const { id, status, cursor } = row;
81
+ if (typeof id !== 'string' ||
82
+ !isMap(scopes) ||
83
+ !Object.values(scopes).every((value) => typeof value === 'string') ||
84
+ (status !== 'active' && status !== 'revoked' && status !== 'failed') ||
85
+ (cursor !== null && !Number.isInteger(cursor)) ||
86
+ !isStrings(seeded) ||
87
+ (echo !== undefined &&
88
+ !(Array.isArray(echo) &&
89
+ echo.every((record) => isMap(record) &&
90
+ typeof record.table === 'string' &&
91
+ (record.status === 'active' || record.status === 'revoked') &&
92
+ isMap(record.scopes) &&
93
+ Object.values(record.scopes).every(isStrings)))))
94
+ throw corrupt();
95
+ const record = {
96
+ id,
97
+ scopes: scopes,
98
+ explicit: row.explicit === 1,
99
+ status,
100
+ seeded,
27
101
  };
102
+ const reasonCode = optionalText(row.reason_code);
103
+ if (reasonCode !== undefined)
104
+ record.reasonCode = reasonCode;
105
+ if (typeof cursor === 'number')
106
+ record.cursor = cursor;
107
+ const bootstrapState = optionalText(row.bootstrap_state);
108
+ if (bootstrapState !== undefined)
109
+ record.bootstrapState = bootstrapState;
110
+ if (echo !== undefined)
111
+ record.echo = echo;
112
+ return record;
28
113
  }
29
- export function loadSubscriptions(db) {
114
+ /** Every unit in registration order (§4.1). */
115
+ export function loadUnits(db) {
30
116
  return db
31
- .query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} ORDER BY rowid ASC`)
117
+ .query(`SELECT * FROM ${UNITS_TABLE} ORDER BY rowid ASC`)
32
118
  .map(rowToRecord);
33
119
  }
34
- export function getSubscription(db, id) {
35
- const row = db.query(`SELECT * FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [
36
- id,
37
- ])[0];
120
+ export function getUnit(db, id) {
121
+ const row = db.query(`SELECT * FROM ${UNITS_TABLE} WHERE id=?`, [id])[0];
38
122
  return row === undefined ? undefined : rowToRecord(row);
39
123
  }
40
- export function saveSubscription(db, record) {
41
- db.exec(`INSERT OR REPLACE INTO ${SUBSCRIPTIONS_TABLE}(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)`, [
124
+ /** Insert or update in place: an update keeps the registration order. */
125
+ export function saveUnit(db, record) {
126
+ db.exec(`INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo)VALUES(?,?,?,?,?,?,?,?,?)ON CONFLICT(id)DO UPDATE SET explicit=excluded.explicit,status=excluded.status,reason_code=excluded.reason_code,cursor=excluded.cursor,bootstrap_state=excluded.bootstrap_state,seeded=excluded.seeded,echo=excluded.echo`, [
42
127
  record.id,
43
- record.table,
44
128
  JSON.stringify(record.scopes),
45
- record.params ?? null,
46
- record.cursor,
47
- record.bootstrapState ?? null,
48
- record.effectiveScopes === undefined
49
- ? null
50
- : JSON.stringify(record.effectiveScopes),
129
+ record.explicit ? 1 : 0,
51
130
  record.status,
52
131
  record.reasonCode ?? null,
132
+ record.cursor ?? null,
133
+ record.bootstrapState ?? null,
134
+ JSON.stringify(record.seeded),
135
+ record.echo === undefined ? null : JSON.stringify(record.echo),
53
136
  ]);
54
137
  }
55
- export function deleteSubscription(db, id) {
56
- db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
138
+ export function deleteUnit(db, id) {
139
+ db.exec(`DELETE FROM ${UNITS_TABLE} WHERE id=?`, [id]);
57
140
  }
58
141
  /**
59
- * §7.4.3 reset: keep compatible subscription REGISTRATIONS (id, table,
60
- * requested scopes, params — the app's declared intent) but discard all
61
- * synced state (cursor → -1, no resume token, no effective-scope map,
62
- * status → active), so the next round fresh-bootstraps exactly the
63
- * subscriptions the app still wants. Caller owns the transaction.
142
+ * §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
143
+ * registrations (the app's declared intent) and discard every synced state,
144
+ * so the next round sends the list and fresh-bootstraps every unit. Caller
145
+ * owns the transaction.
64
146
  */
65
- export function resetSubscriptionsForBump(db) {
66
- db.exec(`UPDATE ${SUBSCRIPTIONS_TABLE} SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL`);
147
+ export function resetUnits(db) {
148
+ db.exec(`UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL`);
149
+ db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?,?)`, [
150
+ REPLICA_CURSOR_KEY,
151
+ ECHO_DIGEST_KEY,
152
+ REGISTERED_DIGEST_KEY,
153
+ ]);
154
+ }
155
+ /** §4.5: the replica cursor, `-1` while no unit is live. */
156
+ export function replicaCursor(db) {
157
+ return Number(getMeta(db, REPLICA_CURSOR_KEY) ?? -1);
67
158
  }
68
- /** Persist declarations separately from the previous-version row descriptor. */
69
- export function saveSubscriptionScopeSchema(db, schema) {
159
+ /** §7.4.3 declaration evidence, persisted beside the schema marker. */
160
+ export function saveUnitScopeSchema(db, schema) {
70
161
  const declarations = {};
71
162
  for (const table of schema.tables.values()) {
72
163
  declarations[table.name] = Object.fromEntries([...table.scopeColumnByVariable].map(([variable, column]) => [
@@ -76,60 +167,58 @@ export function saveSubscriptionScopeSchema(db, schema) {
76
167
  }
77
168
  setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
78
169
  }
79
- /** Drop incompatible registrations and their windows; never translate scopes. */
80
- export function pruneUnknownSubscriptions(db, subscriptions, schema, bump = false) {
170
+ /**
171
+ * Drop units that cover no table of the running schema, with their window
172
+ * registry rows and pending evictions; never translate scopes. At a bump
173
+ * (§7.4.3) a unit also needs every variable unchanged in prefix and column on
174
+ * every table it covered before.
175
+ */
176
+ export function pruneUnknownUnits(db, schema, bump = false) {
81
177
  const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
82
178
  const previous = stored === undefined
83
179
  ? undefined
84
180
  : JSON.parse(stored);
85
- const compatible = (record) => {
86
- const table = schema.tables.get(record.table);
87
- if (table === undefined)
88
- return false;
89
- const variables = Object.keys(record.scopes);
90
- if (!variables.every((variable) => table.scopeColumnByVariable.has(variable)))
181
+ // A table keeps the variables' meaning when each has the same prefix and
182
+ // column as before. An old binary stored no declaration evidence; matching
183
+ // names cannot prove unchanged meaning, so the app registers again.
184
+ const unchanged = (name, variables) => {
185
+ const old = previous?.[name];
186
+ const table = schema.tables.get(name);
187
+ return (old !== undefined &&
188
+ table !== undefined &&
189
+ variables.every((variable) => old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
190
+ old[variable]?.[1] === table.scopeColumnByVariable.get(variable)));
191
+ };
192
+ const compatible = (scopes) => {
193
+ const variables = Object.keys(scopes);
194
+ if (![...schema.tables.values()].some((table) => covers(table, scopes)))
91
195
  return false;
92
196
  if (!bump)
93
197
  return true;
94
- // An old binary stored no declaration evidence. Re-registration is required
95
- // at a bump: matching names cannot prove unchanged column/prefix meaning.
96
- const old = previous?.[record.table];
97
- if (old === undefined)
198
+ if (previous === undefined)
98
199
  return false;
99
- const compared = variables.length === 0
100
- ? [
101
- ...new Set([
102
- ...Object.keys(old),
103
- ...table.scopeColumnByVariable.keys(),
104
- ]),
105
- ]
106
- : variables;
107
- return compared.every((variable) => old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
108
- old[variable]?.[1] === table.scopeColumnByVariable.get(variable));
200
+ return Object.entries(previous).every(([name, old]) => !variables.every((variable) => old[variable] !== undefined) ||
201
+ unchanged(name, variables));
109
202
  };
110
- const retained = subscriptions.filter(compatible);
111
- const staleIds = new Set(subscriptions
112
- .filter((record) => !compatible(record))
113
- .map((record) => record.id));
114
- // Shrinking a pinned window already removed its registration. Its deferred
115
- // eviction still carries the old scope declaration and needs the same fence.
116
- for (const row of db.query(`SELECT sub_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`)) {
117
- if (!compatible({
118
- table: String(row.tbl),
119
- scopes: JSON.parse(String(row.effective_scopes)),
120
- }))
121
- staleIds.add(String(row.sub_id));
203
+ const stale = new Set(loadUnits(db)
204
+ .filter((unit) => !compatible(unit.scopes))
205
+ .map((unit) => unit.id));
206
+ // A shrunk window's deferred eviction outlives its unit row and keeps its
207
+ // per-table scopes. A table the schema no longer has cannot be evicted, and
208
+ // at a bump a table whose scope declarations changed must not be evicted by
209
+ // the outdated rule.
210
+ for (const row of db.query(`SELECT unit_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`)) {
211
+ const table = String(row.tbl);
212
+ if (!schema.tables.has(table) ||
213
+ (bump &&
214
+ !unchanged(table, Object.keys(JSON.parse(String(row.effective_scopes))))))
215
+ stale.add(String(row.unit_id));
216
+ }
217
+ for (const id of stale) {
218
+ db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
219
+ db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
220
+ deleteUnit(db, id);
122
221
  }
123
- if (staleIds.size === 0)
124
- return retained;
125
- db.transaction(() => {
126
- for (const id of staleIds) {
127
- db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
128
- db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id=?`, [id]);
129
- db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
130
- }
131
- });
132
- return retained;
133
222
  }
134
223
  export function getMeta(db, key) {
135
224
  const row = db.query(`SELECT value FROM ${META_TABLE} WHERE key=?`, [key])[0];
@@ -14,7 +14,7 @@ export function installSyncScheduler(client, options = {}) {
14
14
  let backgroundReady = false;
15
15
  let backgroundDue = Number.POSITIVE_INFINITY;
16
16
  let cancelBackground;
17
- // §7.6 backoff for drives that end without a client retry intent.
17
+ // §7.7 backoff for drives that end without a client retry intent.
18
18
  let retryDelayMs = 250;
19
19
  const report = (error) => {
20
20
  if (options.onError !== undefined) {
@@ -70,7 +70,7 @@ export function installSyncScheduler(client, options = {}) {
70
70
  if (stopped)
71
71
  return;
72
72
  report(error);
73
- // §7.7: a retryable drive rejection owes another drive. A retryable
73
+ // §7.8: a retryable drive rejection owes another drive. A retryable
74
74
  // round failure already handed this loop its background intent; the
75
75
  // drive deadline did not. An unreachable endpoint waits for the
76
76
  // host's connectivity resume (§1.8).
@@ -6,7 +6,7 @@
6
6
  */
7
7
  /**
8
8
  * One combined push+pull round trip: SSP2 request bytes → response bytes.
9
- * `signal` aborts when the `syncUntilIdle` deadline elapses (§7.7); a
9
+ * `signal` aborts when the `syncUntilIdle` deadline elapses (§7.8); a
10
10
  * transport that honors it releases the round instead of holding it open.
11
11
  */
12
12
  export type SyncTransport = (request: Uint8Array, signal?: AbortSignal) => Promise<Uint8Array>;
@@ -32,7 +32,7 @@ export interface SegmentFetchRequest {
32
32
  */
33
33
  readonly byteLength?: number;
34
34
  readonly onProgress?: (bytesReceived: number) => void;
35
- /** Aborts with the round when the `syncUntilIdle` deadline elapses (§7.7). */
35
+ /** Aborts with the round when the `syncUntilIdle` deadline elapses (§7.8). */
36
36
  readonly signal?: AbortSignal;
37
37
  }
38
38
  /**
package/dist/window.d.ts CHANGED
@@ -1,20 +1,18 @@
1
- export declare const PENDING_EVICTIONS = "_syncular_window_pending_evict";
1
+ export declare const PENDING_EVICTIONS = "_syncular_pending_evictions";
2
2
  export declare const WINDOWS_TABLE = "_syncular_windows";
3
3
  /**
4
- * Windowed subscriptions (SPEC.md §4.8).
4
+ * Windows (SPEC.md §4.8).
5
5
  *
6
6
  * A window is a partial local replica keyed by scope VALUES: the client
7
- * holds rows for a chosen set of units (one scope value each) of a window
8
- * BASE (a table + one scope variable + the fixed remainder of the scope
9
- * map). Windowing is a set-difference on §4 subscriptions — never a
10
- * mutation of one — so it needs zero wire or server changes.
7
+ * holds the units of a chosen set of values of a window BASE (one scope
8
+ * variable plus fixed values). Windowing is a set difference on §4.1 units,
9
+ * never a mutation of one, so it needs no wire or server change.
11
10
  *
12
- * This module owns the registry bookkeeping and the deterministic
13
- * per-unit subscription-id derivation (§4.1 guidance). The eviction that
14
- * fuses with a shrink (E1–E4) lives on the client, which holds the DB
15
- * transaction and the invalidation choke point.
11
+ * This module owns the registry bookkeeping. The eviction that fuses with a
12
+ * shrink (E1–E4) lives on the client, which holds the DB transaction and the
13
+ * invalidation choke point.
16
14
  */
17
- import { type ScopeMap } from '@syncular/core';
15
+ import { type ScopeMap, type UnitScopes } from '@syncular/core';
18
16
  import type { ClientDatabase } from './database.js';
19
17
  export type TimeBucketUnit = 'month';
20
18
  /** Derive the immutable UTC scope value stored when a row is created. */
@@ -22,55 +20,35 @@ export declare function creationTimeBucket(createdAtMs: number, unit: TimeBucket
22
20
  /** Return a rolling UTC month window ordered from oldest to newest. */
23
21
  export declare function last(count: number, unit: TimeBucketUnit, nowMs?: number): string[];
24
22
  /**
25
- * A window base: one table, one variable whose values are the window
26
- * units, and any FIXED scopes every unit shares (other variables pinned
27
- * to a constant set). `params` is host-opaque, carried onto every unit's
28
- * subscription verbatim.
23
+ * A window base (§4.8): the selected scope variable plus the fixed scope
24
+ * values every unit of its family shares. A base names no table: each unit
25
+ * covers every table declaring its variables (§4.1).
29
26
  */
30
27
  export interface WindowBase {
31
- readonly table: string;
32
28
  /** The scope variable whose values are the window units. */
33
29
  readonly variable: string;
34
- /** Scopes shared by every unit (other variables), if any. */
35
- readonly fixedScopes?: Readonly<Record<string, readonly string[]>>;
36
- readonly params?: string;
37
- }
38
- /** A live unit in the registry: its value and the subscription it drives. */
39
- export interface WindowUnit {
40
- readonly unit: string;
41
- readonly subId: string;
30
+ /** One value per other variable, shared by every unit. */
31
+ readonly fixedScopes?: UnitScopes;
42
32
  }
43
- export interface RegisteredWindowUnit extends WindowUnit {
44
- readonly baseKey: string;
45
- }
46
- /**
47
- * A stable, server-opaque key for a window base — table + variable +
48
- * canonical fixed scopes. Two `setWindow` calls with the same base
49
- * address the same registry rows.
50
- */
33
+ /** A stable key for a window base: variable + canonical fixed scopes. */
51
34
  export declare function windowBaseKey(base: WindowBase): string;
52
- /** The full requested scope map for one unit (fixed scopes + the unit). */
53
- export declare function unitScopes(base: WindowBase, unit: string): ScopeMap;
54
- /**
55
- * Deterministic per-unit subscription id (§4.1 guidance):
56
- * `w:<table>:<sha256(canonical scope map, §11.2)[0..16]>`. Ids are echoed
57
- * not interpreted by the server (§4.1), so the exact hash is pure client
58
- * convention; SHA-256 matches the SPEC's worked example.
59
- */
60
- export declare function deriveSubId(base: WindowBase, unit: string): Promise<string>;
61
- /** Live units for a base, ordered by unit value. */
62
- export declare function loadWindowUnits(db: ClientDatabase, baseKey: string): WindowUnit[];
63
- /** Registry lookup used to emit exact completion changes for a sub id. */
64
- export declare function getWindowUnitBySubId(db: ClientDatabase, subId: string): RegisteredWindowUnit | undefined;
65
- export declare function insertWindowUnit(db: ClientDatabase, baseKey: string, unit: string, subId: string): void;
66
- export declare function deleteWindowUnit(db: ClientDatabase, baseKey: string, unit: string): void;
67
- /** Is a single scope value windowed-in for this base? (the oracle, I3) */
68
- export declare function isUnitLive(db: ClientDatabase, baseKey: string, unit: string): boolean;
35
+ /** The unit of one window value: the fixed scopes plus the value. */
36
+ export declare function windowUnitScopes(base: WindowBase, value: string): UnitScopes;
37
+ /** Registry rows for a base, ordered by value: value → unit id. */
38
+ export declare function loadWindowUnits(db: ClientDatabase, baseKey: string): {
39
+ readonly value: string;
40
+ readonly unitId: string;
41
+ }[];
42
+ /** Every window registry row that references a unit (§4.1 references). */
43
+ export declare function windowRefs(db: ClientDatabase, unitId: string): {
44
+ readonly baseKey: string;
45
+ readonly value: string;
46
+ }[];
69
47
  export interface PendingEviction {
70
- readonly subId: string;
48
+ readonly unitId: string;
71
49
  readonly table: string;
72
50
  readonly effective: ScopeMap;
73
51
  }
74
- export declare function savePendingEviction(db: ClientDatabase, subId: string, table: string, effective: ScopeMap): void;
75
- export declare function deletePendingEviction(db: ClientDatabase, subId: string): void;
52
+ export declare function savePendingEviction(db: ClientDatabase, entry: PendingEviction): void;
53
+ export declare function deletePendingEviction(db: ClientDatabase, unitId: string, table?: string): void;
76
54
  export declare function loadPendingEvictions(db: ClientDatabase): PendingEviction[];
package/dist/window.js CHANGED
@@ -1,20 +1,18 @@
1
- export const PENDING_EVICTIONS = '_syncular_window_pending_evict';
1
+ export const PENDING_EVICTIONS = '_syncular_pending_evictions';
2
2
  export const WINDOWS_TABLE = '_syncular_windows';
3
3
  /**
4
- * Windowed subscriptions (SPEC.md §4.8).
4
+ * Windows (SPEC.md §4.8).
5
5
  *
6
6
  * A window is a partial local replica keyed by scope VALUES: the client
7
- * holds rows for a chosen set of units (one scope value each) of a window
8
- * BASE (a table + one scope variable + the fixed remainder of the scope
9
- * map). Windowing is a set-difference on §4 subscriptions — never a
10
- * mutation of one — so it needs zero wire or server changes.
7
+ * holds the units of a chosen set of values of a window BASE (one scope
8
+ * variable plus fixed values). Windowing is a set difference on §4.1 units,
9
+ * never a mutation of one, so it needs no wire or server change.
11
10
  *
12
- * This module owns the registry bookkeeping and the deterministic
13
- * per-unit subscription-id derivation (§4.1 guidance). The eviction that
14
- * fuses with a shrink (E1–E4) lives on the client, which holds the DB
15
- * transaction and the invalidation choke point.
11
+ * This module owns the registry bookkeeping. The eviction that fuses with a
12
+ * shrink (E1–E4) lives on the client, which holds the DB transaction and the
13
+ * invalidation choke point.
16
14
  */
17
- import { canonicalScopeJson } from '@syncular/core';
15
+ import { canonicalUnitJson, } from '@syncular/core';
18
16
  import { invalidRequest } from './errors.js';
19
17
  const MAX_TIME_BUCKET_MS = 253_402_300_799_999;
20
18
  function monthBucket(year, month) {
@@ -54,85 +52,43 @@ export function last(count, unit, nowMs = Date.now()) {
54
52
  }
55
53
  return units;
56
54
  }
57
- /**
58
- * A stable, server-opaque key for a window base — table + variable +
59
- * canonical fixed scopes. Two `setWindow` calls with the same base
60
- * address the same registry rows.
61
- */
55
+ /** A stable key for a window base: variable + canonical fixed scopes. */
62
56
  export function windowBaseKey(base) {
63
- const fixed = canonicalScopeJson(base.fixedScopes ?? {});
64
- return `${base.table}\0${base.variable}\0${fixed}`;
65
- }
66
- /** The full requested scope map for one unit (fixed scopes + the unit). */
67
- export function unitScopes(base, unit) {
68
- const scopes = {};
69
- for (const [variable, values] of Object.entries(base.fixedScopes ?? {})) {
70
- scopes[variable] = [...values];
71
- }
72
- scopes[base.variable] = [unit];
73
- return scopes;
57
+ return `${base.variable}\0${canonicalUnitJson(base.fixedScopes ?? {})}`;
74
58
  }
75
- /**
76
- * Deterministic per-unit subscription id (§4.1 guidance):
77
- * `w:<table>:<sha256(canonical scope map, §11.2)[0..16]>`. Ids are echoed
78
- * not interpreted by the server (§4.1), so the exact hash is pure client
79
- * convention; SHA-256 matches the SPEC's worked example.
80
- */
81
- export async function deriveSubId(base, unit) {
82
- const canonical = canonicalScopeJson(unitScopes(base, unit));
83
- const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical));
84
- let hex = '';
85
- for (const byte of new Uint8Array(digest)) {
86
- hex += byte.toString(16).padStart(2, '0');
87
- }
88
- return `w:${base.table}:${hex.slice(0, 16)}`;
59
+ /** The unit of one window value: the fixed scopes plus the value. */
60
+ export function windowUnitScopes(base, value) {
61
+ return { ...base.fixedScopes, [base.variable]: value };
89
62
  }
90
- /** Live units for a base, ordered by unit value. */
63
+ /** Registry rows for a base, ordered by value: value → unit id. */
91
64
  export function loadWindowUnits(db, baseKey) {
92
65
  return db
93
66
  .query(`SELECT unit,sub_id FROM ${WINDOWS_TABLE} WHERE base=? ORDER BY unit`, [baseKey])
94
- .map((row) => ({ unit: row.unit, subId: row.sub_id }));
95
- }
96
- /** Registry lookup used to emit exact completion changes for a sub id. */
97
- export function getWindowUnitBySubId(db, subId) {
98
- const row = db.query(`SELECT base, unit, sub_id FROM ${WINDOWS_TABLE}
99
- WHERE sub_id = ? LIMIT 1`, [subId])[0];
100
- return row === undefined
101
- ? undefined
102
- : {
103
- baseKey: row.base,
104
- unit: row.unit,
105
- subId: row.sub_id,
106
- };
107
- }
108
- export function insertWindowUnit(db, baseKey, unit, subId) {
109
- db.exec(`INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`, [baseKey, unit, subId]);
110
- }
111
- export function deleteWindowUnit(db, baseKey, unit) {
112
- db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE base=? AND unit=?`, [
113
- baseKey,
114
- unit,
115
- ]);
67
+ .map((row) => ({
68
+ value: row.unit,
69
+ unitId: row.sub_id,
70
+ }));
116
71
  }
117
- /** Is a single scope value windowed-in for this base? (the oracle, I3) */
118
- export function isUnitLive(db, baseKey, unit) {
119
- return (db.query(`SELECT 1 FROM ${WINDOWS_TABLE} WHERE base=? AND unit=? LIMIT 1`, [
120
- baseKey,
121
- unit,
122
- ]).length > 0);
72
+ /** Every window registry row that references a unit (§4.1 references). */
73
+ export function windowRefs(db, unitId) {
74
+ return db
75
+ .query(`SELECT base,unit FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [unitId])
76
+ .map((row) => ({
77
+ baseKey: row.base,
78
+ value: row.unit,
79
+ }));
123
80
  }
124
- export function savePendingEviction(db, subId, table, effective) {
125
- db.exec(`INSERT OR REPLACE INTO ${PENDING_EVICTIONS}(sub_id, tbl, effective_scopes)
126
- VALUES (?, ?, ?)`, [subId, table, JSON.stringify(effective)]);
81
+ export function savePendingEviction(db, entry) {
82
+ db.exec(`INSERT OR REPLACE INTO ${PENDING_EVICTIONS}(unit_id,tbl,effective_scopes)VALUES(?,?,?)`, [entry.unitId, entry.table, JSON.stringify(entry.effective)]);
127
83
  }
128
- export function deletePendingEviction(db, subId) {
129
- db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id = ?`, [subId]);
84
+ export function deletePendingEviction(db, unitId, table) {
85
+ db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?${table === undefined ? '' : ' AND tbl=?'}`, table === undefined ? [unitId] : [unitId, table]);
130
86
  }
131
87
  export function loadPendingEvictions(db) {
132
88
  return db
133
- .query(`SELECT sub_id, tbl, effective_scopes FROM ${PENDING_EVICTIONS}`)
89
+ .query(`SELECT unit_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`)
134
90
  .map((row) => ({
135
- subId: row.sub_id,
91
+ unitId: row.unit_id,
136
92
  table: row.tbl,
137
93
  effective: JSON.parse(row.effective_scopes),
138
94
  }));
@@ -76,7 +76,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
76
76
  let autoSyncScheduled = false;
77
77
  let cancelBackground;
78
78
  let backgroundDue = Number.POSITIVE_INFINITY;
79
- // §7.6 backoff for drives that end without a client retry intent.
79
+ // §7.7 backoff for drives that end without a client retry intent.
80
80
  let retryDelayMs = 250;
81
81
  const scheduleBackground = overrides.scheduleBackground ??
82
82
  ((callback, delayMs) => {
@@ -127,7 +127,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
127
127
  t: 'event',
128
128
  event: { kind: 'synced', error: toErrorShape(error) },
129
129
  });
130
- // §7.7: a retryable drive rejection owes another drive. A retryable
130
+ // §7.8: a retryable drive rejection owes another drive. A retryable
131
131
  // round failure already handed this loop its background intent; the
132
132
  // drive deadline did not. An unreachable endpoint waits for the
133
133
  // host's connectivity resume (§1.8).
@@ -360,8 +360,8 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
360
360
  'commitOutcomes',
361
361
  'resolveCommitOutcome',
362
362
  'pendingCommits',
363
- 'subscriptions',
364
- 'subscription',
363
+ 'units',
364
+ 'unit',
365
365
  'connectRealtime',
366
366
  'disconnectRealtime',
367
367
  'setPresence',
@@ -415,7 +415,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
415
415
  },
416
416
  resetClientId: () => requireClient().resetClientId(),
417
417
  localRevision: () => requireClient().localRevision,
418
- diagnosticsSnapshot: (request) => {
418
+ diagnosticsSnapshot: () => {
419
419
  const running = requireClient();
420
420
  // The first pull makes the worker a push source: no tab has asked for
421
421
  // diagnostics before it, so no snapshot is built per revision until then.
@@ -423,7 +423,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
423
423
  pushingDiagnostics = true;
424
424
  running.onDiagnostics(postDiagnostics);
425
425
  }
426
- return workerDiagnostics(running.diagnosticsSnapshot(request));
426
+ return workerDiagnostics(running.diagnosticsSnapshot());
427
427
  },
428
428
  setHeaders: (next) => {
429
429
  headers = next;