@gusto/baerly-storage 0.1.1 → 0.2.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 (114) hide show
  1. package/README.md +27 -3
  2. package/dist/API.md +103 -22
  3. package/dist/{app-config-Dj_nGBfj.d.ts → app-config-C0Bbw_Z6.d.ts} +9 -9
  4. package/dist/app-config.d.ts +1 -1
  5. package/dist/auth.d.ts +1 -1
  6. package/dist/baerly.js +10 -10
  7. package/dist/baerly.js.map +1 -1
  8. package/dist/bytes-BXdamO3L.js +11 -0
  9. package/dist/bytes-BXdamO3L.js.map +1 -0
  10. package/dist/{client-CC5yVs1S.d.ts → client-DYZfoZb9.d.ts} +3 -3
  11. package/dist/client-react.d.ts +76 -85
  12. package/dist/client-react.js +95 -53
  13. package/dist/client-react.js.map +1 -1
  14. package/dist/client.d.ts +3 -3
  15. package/dist/cloudflare.d.ts +31 -4
  16. package/dist/cloudflare.js +72 -6
  17. package/dist/cloudflare.js.map +1 -1
  18. package/dist/{config-Bsg8wgwo.js → config-DVfDGyw1.js} +82 -2
  19. package/dist/config-DVfDGyw1.js.map +1 -0
  20. package/dist/{context-Oj7ffwD-.js → context-DRZ3tZ5l.js} +3 -2
  21. package/dist/{context-Oj7ffwD-.js.map → context-DRZ3tZ5l.js.map} +1 -1
  22. package/dist/{cost-B1WiZxlf.js → cost-CQt1YRkA.js} +3 -4
  23. package/dist/{cost-B1WiZxlf.js.map → cost-CQt1YRkA.js.map} +1 -1
  24. package/dist/{current-json-BkatBzF7.js → current-json-C-EyJqs0.js} +107 -5
  25. package/dist/current-json-C-EyJqs0.js.map +1 -0
  26. package/dist/{db-aRMK_0R0.d.ts → db-BM3y2JQw.d.ts} +3 -3
  27. package/dist/{deploy-BB-wqbhf.js → deploy-CrAbfgCq.js} +2 -2
  28. package/dist/{deploy-BB-wqbhf.js.map → deploy-CrAbfgCq.js.map} +1 -1
  29. package/dist/dev-vite.d.ts +3 -3
  30. package/dist/dev-vite.js +3 -3
  31. package/dist/dev.d.ts +1 -1
  32. package/dist/dev.js +1 -1
  33. package/dist/{doctor-B8h9GCN9.js → doctor-Db-hzPmE.js} +144 -7
  34. package/dist/doctor-Db-hzPmE.js.map +1 -0
  35. package/dist/{dump-BHo_sIMZ.js → dump-BYA55NLP.js} +3 -4
  36. package/dist/{dump-BHo_sIMZ.js.map → dump-BYA55NLP.js.map} +1 -1
  37. package/dist/errors-DOdL95kK.js.map +1 -1
  38. package/dist/{export-Dz2PZKSR.js → export-Bhbz90-z.js} +4 -5
  39. package/dist/{export-Dz2PZKSR.js.map → export-Bhbz90-z.js.map} +1 -1
  40. package/dist/{fsck-DEz9lyCy.js → fsck-CPPZWt9p.js} +5 -8
  41. package/dist/fsck-CPPZWt9p.js.map +1 -0
  42. package/dist/{http-DeJEeUcO.js → http-Cw8p6y5b.js} +5 -5
  43. package/dist/{http-DeJEeUcO.js.map → http-Cw8p6y5b.js.map} +1 -1
  44. package/dist/http.d.ts +3 -3
  45. package/dist/http.js +1 -1
  46. package/dist/{index-m6pY8iRU.d.ts → index-C3JAH1Yo.d.ts} +14 -2
  47. package/dist/{index-5lX_5NxZ.d.ts → index-DSvwEUeF.d.ts} +63 -54
  48. package/dist/{index-DPaQhAro.d.ts → index-DwDTWPSU.d.ts} +2 -2
  49. package/dist/{index-spCBsIwm.d.ts → index-cUY-36AN.d.ts} +3 -3
  50. package/dist/index.d.ts +5 -5
  51. package/dist/index.js +3 -3
  52. package/dist/{indexes-BIH73Uv4.d.ts → indexes-DAu2AkTW.d.ts} +2 -2
  53. package/dist/{inspect-x02aFWnh.js → inspect-Bdbzvi-_.js} +5 -6
  54. package/dist/{inspect-x02aFWnh.js.map → inspect-Bdbzvi-_.js.map} +1 -1
  55. package/dist/maintenance-BRrThz8V.d.ts +449 -0
  56. package/dist/maintenance-BvOv6BMM.js +1295 -0
  57. package/dist/maintenance-BvOv6BMM.js.map +1 -0
  58. package/dist/maintenance-ClzBC1Vv.js +1895 -0
  59. package/dist/maintenance-ClzBC1Vv.js.map +1 -0
  60. package/dist/maintenance.d.ts +2 -323
  61. package/dist/maintenance.js +2 -2
  62. package/dist/node.d.ts +20 -79
  63. package/dist/node.js +2 -2
  64. package/dist/{observability-2IDYRuZK.js → observability-CpOiEN0k.js} +2 -2
  65. package/dist/{observability-2IDYRuZK.js.map → observability-CpOiEN0k.js.map} +1 -1
  66. package/dist/observability.d.ts +2 -2
  67. package/dist/observability.js +2 -2
  68. package/dist/{plan-Cs17VqjU.js → plan-DOTl21vq.js} +3 -4
  69. package/dist/{plan-Cs17VqjU.js.map → plan-DOTl21vq.js.map} +1 -1
  70. package/dist/{query-DcSbFLJt.js → query-BmiQy328.js} +58 -26
  71. package/dist/query-BmiQy328.js.map +1 -0
  72. package/dist/{rebuild-index-DwXM0WfA.js → rebuild-index-DC_nR6wP.js} +4 -5
  73. package/dist/{rebuild-index-DwXM0WfA.js.map → rebuild-index-DC_nR6wP.js.map} +1 -1
  74. package/dist/{restore-CbKVMMpm.js → restore-C6IcmLeA.js} +44 -120
  75. package/dist/restore-C6IcmLeA.js.map +1 -0
  76. package/dist/{log-walk-DIru96UT.js → snapshot-SS8USDUF.js} +187 -20
  77. package/dist/snapshot-SS8USDUF.js.map +1 -0
  78. package/dist/{src-Cr9C7_tT.js → src-DU1sCMlr.js} +315 -278
  79. package/dist/src-DU1sCMlr.js.map +1 -0
  80. package/dist/{src-n0Te1r98.js → src-QQ7jDeL2.js} +25 -6
  81. package/dist/src-QQ7jDeL2.js.map +1 -0
  82. package/dist/{src-Chafbw8r.js → src-zhEAmmF7.js} +35 -4
  83. package/dist/src-zhEAmmF7.js.map +1 -0
  84. package/dist/{bucket-uri-BrDEYvzy.js → subcommand-DZcHcsYp.js} +222 -22
  85. package/dist/subcommand-DZcHcsYp.js.map +1 -0
  86. package/dist/{usage-RVUQMLop.js → usage-CLjirdD-.js} +4 -4
  87. package/dist/{usage-RVUQMLop.js.map → usage-CLjirdD-.js.map} +1 -1
  88. package/dist/{validate-DhH1lO8I.js → validate-DCq_0DIn.js} +2 -2
  89. package/dist/validate-DCq_0DIn.js.map +1 -0
  90. package/package.json +13 -6
  91. package/dist/bucket-uri-BrDEYvzy.js.map +0 -1
  92. package/dist/config-Bsg8wgwo.js.map +0 -1
  93. package/dist/current-json-BkatBzF7.js.map +0 -1
  94. package/dist/doctor-B8h9GCN9.js.map +0 -1
  95. package/dist/fsck-DEz9lyCy.js.map +0 -1
  96. package/dist/indexes-BXn7a06a.js +0 -297
  97. package/dist/indexes-BXn7a06a.js.map +0 -1
  98. package/dist/log-walk-DIru96UT.js.map +0 -1
  99. package/dist/maintenance-Bn6ul9aV.js +0 -758
  100. package/dist/maintenance-Bn6ul9aV.js.map +0 -1
  101. package/dist/query-DcSbFLJt.js.map +0 -1
  102. package/dist/rebuild-index-C5gTXryd.js +0 -119
  103. package/dist/rebuild-index-C5gTXryd.js.map +0 -1
  104. package/dist/restore-CbKVMMpm.js.map +0 -1
  105. package/dist/snapshot-D7C4_FSl.js +0 -71
  106. package/dist/snapshot-D7C4_FSl.js.map +0 -1
  107. package/dist/snapshot-z_N9hpTe.js +0 -917
  108. package/dist/snapshot-z_N9hpTe.js.map +0 -1
  109. package/dist/src-Chafbw8r.js.map +0 -1
  110. package/dist/src-Cr9C7_tT.js.map +0 -1
  111. package/dist/src-n0Te1r98.js.map +0 -1
  112. package/dist/subcommand-BWs6K7zb.js +0 -110
  113. package/dist/subcommand-BWs6K7zb.js.map +0 -1
  114. package/dist/validate-DhH1lO8I.js.map +0 -1
@@ -1,917 +0,0 @@
1
- import { f as decodeJsonBytes, p as encodeJsonBytes } from "./current-json-BkatBzF7.js";
2
- import { t as BaerlyError } from "./errors-DOdL95kK.js";
3
- //#region packages/protocol/src/query/_internals.ts
4
- /** @internal Same primitive type for comparison purposes. */
5
- const sameComparableType = (a, b) => typeof a === "string" && typeof b === "string" || typeof a === "number" && typeof b === "number";
6
- /**
7
- * @internal Returns negative / zero / positive for a<b / a==b / a>b.
8
- */
9
- const compareScalar = (a, b) => {
10
- if (typeof a === "number" && typeof b === "number") return a - b;
11
- if (typeof a === "string" && typeof b === "string") {
12
- if (a < b) return -1;
13
- if (a > b) return 1;
14
- return 0;
15
- }
16
- return 0;
17
- };
18
- /** @internal Render a predicate path for use in error messages. */
19
- const formatPath = (path) => path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(".");
20
- /**
21
- * Recursive structural equality for `DocumentValue` values. Lifted to
22
- * `export` so the filtered-index implication checker (in
23
- * `@baerly/server`'s query planner) and other callers can reuse the
24
- * same comparison rule the validator + merger already trust. Two
25
- * values `a` and `b` are equal iff:
26
- *
27
- * - they are reference-equal (covers primitives and object identity);
28
- * - or they are both non-`null` objects with the same key set, and
29
- * every value pair is recursively equal.
30
- *
31
- * Arrays are out-of-band for `DocumentValue`; this function rejects
32
- * them implicitly via the same key-set walk (an array reads as an
33
- * object with numeric-string keys plus a `length` exposure that
34
- * `Object.keys` happens to skip — defensive callers should still gate
35
- * with `Array.isArray` first).
36
- */
37
- const deepEqualDocumentValue = (a, b) => {
38
- if (a === b) return true;
39
- if (typeof a !== "object" || typeof b !== "object") return false;
40
- const aKeys = Object.keys(a);
41
- const bKeys = Object.keys(b);
42
- if (aKeys.length !== bKeys.length) return false;
43
- for (const key of aKeys) {
44
- if (!(key in b)) return false;
45
- const aSub = a[key];
46
- const bSub = b[key];
47
- if (aSub === void 0 || bSub === void 0) return false;
48
- if (!deepEqualDocumentValue(aSub, bSub)) return false;
49
- }
50
- return true;
51
- };
52
- //#endregion
53
- //#region packages/protocol/src/query/matches.ts
54
- /**
55
- * Evaluate a validated wire-form predicate against a `JSONObject`
56
- * document. Returns `true` iff every clause holds.
57
- *
58
- * @example
59
- * ```ts
60
- * matchesWire(
61
- * { clauses: [{ op: "eq", field: "status", value: "open" }] },
62
- * { status: "open", priority: "p1" },
63
- * ); // true
64
- *
65
- * matchesWire(
66
- * { clauses: [{ op: "in", field: "priority", value: ["p1", "p2"] }] },
67
- * { priority: "p3" },
68
- * ); // false
69
- *
70
- * matchesWire(
71
- * {
72
- * clauses: [
73
- * { op: "gte", field: "count", value: 1 },
74
- * { op: "lt", field: "count", value: 10 },
75
- * ],
76
- * },
77
- * { count: 5 },
78
- * ); // true
79
- * ```
80
- */
81
- const matchesWire = (wire, doc) => {
82
- for (const clause of wire.clauses) if (!matchesClause(clause, lookupPath(doc, clause.field))) return false;
83
- return true;
84
- };
85
- const lookupPath = (doc, field) => {
86
- if (!field.includes(".")) return doc[field];
87
- const segments = field.split(".");
88
- let cursor = doc;
89
- for (const segment of segments) {
90
- if (cursor === void 0 || cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) return;
91
- cursor = cursor[segment];
92
- }
93
- return cursor;
94
- };
95
- const matchesClause = (clause, actual) => {
96
- switch (clause.op) {
97
- case "eq": return matchesEq(clause.value, actual);
98
- case "in": return matchesIn(clause.value, actual);
99
- case "gt": return compareGT(actual, clause.value, false);
100
- case "gte": return compareGT(actual, clause.value, true);
101
- case "lt": return compareLT(actual, clause.value, false);
102
- case "lte": return compareLT(actual, clause.value, true);
103
- }
104
- };
105
- const matchesEq = (expected, actual) => {
106
- if (typeof expected === "object") {
107
- if (actual === void 0 || actual === null || typeof actual !== "object" || Array.isArray(actual)) return false;
108
- for (const subKey of Object.keys(expected)) {
109
- const subExpected = expected[subKey];
110
- if (subExpected === void 0) continue;
111
- const subActual = actual[subKey];
112
- if (!matchesEq(subExpected, subActual)) return false;
113
- }
114
- return true;
115
- }
116
- return expected === actual;
117
- };
118
- const matchesIn = (members, actual) => {
119
- for (const m of members) if (typeof m === "object") {
120
- if (matchesEq(m, actual)) return true;
121
- } else if (m === actual) return true;
122
- return false;
123
- };
124
- const compareGT = (actual, bound, inclusive) => {
125
- if (typeof bound === "string") return typeof actual === "string" && (inclusive ? actual >= bound : actual > bound);
126
- if (typeof bound === "number") return typeof actual === "number" && (inclusive ? actual >= bound : actual > bound);
127
- return false;
128
- };
129
- const compareLT = (actual, bound, inclusive) => {
130
- if (typeof bound === "string") return typeof actual === "string" && (inclusive ? actual <= bound : actual < bound);
131
- if (typeof bound === "number") return typeof actual === "number" && (inclusive ? actual <= bound : actual < bound);
132
- return false;
133
- };
134
- //#endregion
135
- //#region packages/protocol/src/query/satisfiable.ts
136
- /**
137
- * Per-field satisfiability check for a {@link PredicateWire}. Groups
138
- * clauses by field, then runs the same logic the pre-redesign
139
- * `assertOpObjectSatisfiable` ran on a single op-object — but
140
- * generalised across N clauses on the same field (the wire merger
141
- * concatenates lists without coalescing).
142
- *
143
- * Triggers:
144
- * - Two `eq` clauses on the same field with different values →
145
- * `InvalidConfig` (the same conflict that pre-redesign
146
- * `mergePredicates` threw on shared primitive keys).
147
- * - Range bounds with `lo > hi` (or `lo == hi` with strict on
148
- * either side) → `UnsatisfiablePredicate`.
149
- * - `eq` value outside the residual range interval or absent from
150
- * every `in` set on the same field → `UnsatisfiablePredicate`.
151
- * - `in` sets that intersect to empty across multiple clauses →
152
- * `UnsatisfiablePredicate`.
153
- *
154
- * Used by both `./validate.ts` (wire-arrival check) and
155
- * `./merge.ts` (post-merge re-check, kept in lockstep).
156
- */
157
- const groupByField = (wire) => {
158
- const out = /* @__PURE__ */ new Map();
159
- for (const clause of wire.clauses) {
160
- let group = out.get(clause.field);
161
- if (group === void 0) {
162
- group = {
163
- eqs: [],
164
- ins: []
165
- };
166
- out.set(clause.field, group);
167
- }
168
- applyClause(group, clause.field, clause);
169
- }
170
- return out;
171
- };
172
- const applyClause = (group, field, clause) => {
173
- switch (clause.op) {
174
- case "eq":
175
- group.eqs.push(clause.value);
176
- return;
177
- case "in":
178
- group.ins.push(clause.value);
179
- return;
180
- case "gt":
181
- tightenLower(group, field, clause.value, false);
182
- return;
183
- case "gte":
184
- tightenLower(group, field, clause.value, true);
185
- return;
186
- case "lt":
187
- tightenUpper(group, field, clause.value, false);
188
- return;
189
- case "lte":
190
- tightenUpper(group, field, clause.value, true);
191
- return;
192
- }
193
- };
194
- const tightenLower = (group, field, value, inclusive) => {
195
- if (group.lo === void 0) {
196
- group.lo = {
197
- value,
198
- inclusive
199
- };
200
- return;
201
- }
202
- if (!sameComparableType(group.lo.value, value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has type-incompatible lower bounds (${JSON.stringify(group.lo.value)} vs ${JSON.stringify(value)}).`);
203
- const c = compareScalar(group.lo.value, value);
204
- if (c < 0 || c === 0 && inclusive === false && group.lo.inclusive === true) group.lo = {
205
- value,
206
- inclusive
207
- };
208
- };
209
- const tightenUpper = (group, field, value, inclusive) => {
210
- if (group.hi === void 0) {
211
- group.hi = {
212
- value,
213
- inclusive
214
- };
215
- return;
216
- }
217
- if (!sameComparableType(group.hi.value, value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has type-incompatible upper bounds (${JSON.stringify(group.hi.value)} vs ${JSON.stringify(value)}).`);
218
- const c = compareScalar(group.hi.value, value);
219
- if (c > 0 || c === 0 && inclusive === false && group.hi.inclusive === true) group.hi = {
220
- value,
221
- inclusive
222
- };
223
- };
224
- const intersectInSets = (sets) => {
225
- if (sets.length === 0) return [];
226
- let acc = sets[0];
227
- for (let i = 1; i < sets.length; i++) {
228
- const next = [];
229
- for (const a of acc) for (const b of sets[i]) if (deepEqualDocumentValue(a, b)) {
230
- next.push(a);
231
- break;
232
- }
233
- acc = next;
234
- }
235
- return acc;
236
- };
237
- /**
238
- * Check that every per-field clause group on `wire` is jointly
239
- * satisfiable. Throws `BaerlyError{code:"UnsatisfiablePredicate"}`
240
- * (or `"InvalidConfig"` for conflicting `eq` clauses) on the
241
- * first contradiction. Returns `void` on success.
242
- */
243
- const assertWireSatisfiable = (wire) => {
244
- const groups = groupByField(wire);
245
- for (const [field, group] of groups) {
246
- if (group.eqs.length > 1) {
247
- for (let i = 1; i < group.eqs.length; i++) if (!deepEqualDocumentValue(group.eqs[0], group.eqs[i])) throw new BaerlyError("InvalidConfig", `Conflicting equality clauses on field ${formatPath([field])} (${JSON.stringify(group.eqs[0])} vs ${JSON.stringify(group.eqs[i])}). Predicate chains must agree on shared equality.`);
248
- }
249
- const eq = group.eqs[0];
250
- if (group.lo !== void 0 && group.hi !== void 0 && sameComparableType(group.lo.value, group.hi.value)) {
251
- const c = compareScalar(group.lo.value, group.hi.value);
252
- if (c > 0 || c === 0 && (!group.lo.inclusive || !group.hi.inclusive)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has empty interval (lo=${JSON.stringify(group.lo.value)} ${group.lo.inclusive ? "gte" : "gt"}, hi=${JSON.stringify(group.hi.value)} ${group.hi.inclusive ? "lte" : "lt"}).`);
253
- }
254
- if (eq !== void 0) {
255
- if (group.lo !== void 0) {
256
- if (!sameComparableType(eq, group.lo.value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} (${typeof eq}) is type-incompatible with lower bound ${JSON.stringify(group.lo.value)} (${typeof group.lo.value}); range ops require matching primitive types.`);
257
- const c = compareScalar(eq, group.lo.value);
258
- if (c < 0 || c === 0 && !group.lo.inclusive) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} excluded by lower bound ${JSON.stringify(group.lo.value)} (${group.lo.inclusive ? "gte" : "gt"}).`);
259
- }
260
- if (group.hi !== void 0) {
261
- if (!sameComparableType(eq, group.hi.value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} (${typeof eq}) is type-incompatible with upper bound ${JSON.stringify(group.hi.value)} (${typeof group.hi.value}); range ops require matching primitive types.`);
262
- const c = compareScalar(eq, group.hi.value);
263
- if (c > 0 || c === 0 && !group.hi.inclusive) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} excluded by upper bound ${JSON.stringify(group.hi.value)} (${group.hi.inclusive ? "lte" : "lt"}).`);
264
- }
265
- if (group.ins.length > 0) for (const set of group.ins) {
266
- let found = false;
267
- for (const m of set) if (deepEqualDocumentValue(eq, m)) {
268
- found = true;
269
- break;
270
- }
271
- if (!found) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} not present in in() set.`);
272
- }
273
- }
274
- if (group.ins.length > 1) {
275
- if (intersectInSets(group.ins).length === 0) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has empty in() intersection across multiple clauses.`);
276
- }
277
- }
278
- };
279
- //#endregion
280
- //#region packages/protocol/src/query/validate.ts
281
- /**
282
- * Wire predicate validator. Walks a {@link PredicateWire} and throws
283
- * on a structurally bad clause (`BaerlyError{code:"InvalidConfig"}`)
284
- * or a per-field clause group that contradicts itself
285
- * (`BaerlyError{code:"UnsatisfiablePredicate"}`).
286
- *
287
- * The object-form normaliser at `./normalize.ts` enforces shape on
288
- * the way in (rejecting `$`-keys / non-scalars / null / undefined);
289
- * the callback builder at `./builder.ts` enforces shape via the
290
- * type system. This validator is the wire-arrival check: it runs
291
- * over already-normalised clauses, defending against raw-`fetch`
292
- * callers who bypass the typed seam and submit arbitrary JSON.
293
- *
294
- * Companion modules: `./matches.ts` (evaluator), `./merge.ts`
295
- * (AND-merge). Shared helpers live in `./_internals.ts`.
296
- */
297
- const OP_NAMES = [
298
- "eq",
299
- "gt",
300
- "gte",
301
- "lt",
302
- "lte",
303
- "in"
304
- ];
305
- const RANGE_OPS = [
306
- "gt",
307
- "gte",
308
- "lt",
309
- "lte"
310
- ];
311
- /**
312
- * Validate a normalised predicate wire. Throws
313
- * `BaerlyError{code:"InvalidConfig"}` on a structurally bad clause,
314
- * or `BaerlyError{code:"UnsatisfiablePredicate"}` when a clause
315
- * group on one field contradicts itself.
316
- *
317
- * Returns the wire unchanged on success — callers can thread the
318
- * validated wire forward.
319
- *
320
- * @example
321
- * ```ts
322
- * validateWire({ clauses: [{ op: "eq", field: "status", value: "open" }] }); // ok
323
- * validateWire({ clauses: [{ op: "in", field: "priority", value: [] }] }); // throws UnsatisfiablePredicate
324
- * validateWire({ clauses: [{ op: "eq", field: "_id", value: "x" }] }); // throws InvalidConfig (top-level _id)
325
- * ```
326
- */
327
- const validateWire = (wire) => {
328
- if (wire === null || typeof wire !== "object" || !Array.isArray(wire.clauses)) throw new BaerlyError("InvalidConfig", `Predicate wire must be an object with a "clauses" array.`);
329
- for (let i = 0; i < wire.clauses.length; i++) validateClause(wire.clauses[i], i);
330
- assertWireSatisfiable(wire);
331
- return wire;
332
- };
333
- const validateClause = (clause, index) => {
334
- if (clause === null || typeof clause !== "object") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} must be an object — got ${JSON.stringify(clause)}.`);
335
- const { op, field, value } = clause;
336
- if (typeof op !== "string" || !OP_NAMES.includes(op)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} has unsupported op ${JSON.stringify(op)} — supported: ${OP_NAMES.join(" / ")}.`);
337
- if (typeof field !== "string" || field.length === 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} has empty / non-string field.`);
338
- if (field === "_id") throw new BaerlyError("InvalidConfig", "Predicates may not key on \"_id\"; use .get(id) / .update(id, patch) / .replace(id, doc) / .delete(id) instead.");
339
- if (op === "in") {
340
- if (!Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} (op="in", field=${JSON.stringify(field)}) must carry an array value.`);
341
- if (value.length === 0) throw new BaerlyError("UnsatisfiablePredicate", `Predicate clause at index ${index} (op="in", field=${JSON.stringify(field)}) has empty value array — no document can match.`);
342
- for (let i = 0; i < value.length; i++) validateMemberValue(value[i], field, index, i);
343
- return;
344
- }
345
- if (Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} (op=${JSON.stringify(op)}, field=${JSON.stringify(field)}) must carry a primitive value, got an array — only op="in" accepts arrays.`);
346
- if (RANGE_OPS.includes(op)) {
347
- validateRangeBound(value, field, index);
348
- return;
349
- }
350
- validateScalar(value, field, index);
351
- };
352
- const validateMemberValue = (value, field, clauseIndex, memberIndex) => {
353
- if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is ${value === null ? "null" : "undefined"} — members must be string / number / boolean / nested object.`);
354
- if (Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is an array — members must be string / number / boolean / nested object.`);
355
- const t = typeof value;
356
- if (t === "object") return;
357
- if (t !== "string" && t !== "number" && t !== "boolean") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} has unsupported type ${JSON.stringify(t)} — must be string / number / boolean / nested object.`);
358
- if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
359
- };
360
- const validateScalar = (value, field, clauseIndex) => {
361
- if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value is ${value === null ? "null" : "undefined"} — terminal values must be string / number / boolean / nested object.`);
362
- const t = typeof value;
363
- if (t === "object") return;
364
- if (t !== "string" && t !== "number" && t !== "boolean") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value has unsupported type ${JSON.stringify(t)} — must be string / number / boolean / nested object.`);
365
- if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
366
- };
367
- const validateRangeBound = (value, field, clauseIndex) => {
368
- if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is ${value === null ? "null" : "undefined"} — range bounds must be string or finite number.`);
369
- const t = typeof value;
370
- if (t === "boolean") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is a boolean — range bounds must be string or finite number (booleans are not ordered).`);
371
- if (t === "object") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is a nested object — range bounds must be string or finite number.`);
372
- if (t !== "string" && t !== "number") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) has unsupported type ${JSON.stringify(t)} — must be string or finite number.`);
373
- if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
374
- };
375
- //#endregion
376
- //#region packages/protocol/src/hashing.ts
377
- /**
378
- * Width of the {@link ContentVersionId} hex strings produced by
379
- * {@link versionFromContent}. 32 hex chars = 128 bits, matching the
380
- * information content of a v4 UUID. Collision probability with
381
- * N=10⁹ writes is ~3 × 10⁻²⁰; ample for a content-addressed version id.
382
- *
383
- * @see docs/spec/log-entry-shape.md §"Content body layout"
384
- */
385
- const VERSION_HEX_LENGTH = 32;
386
- /**
387
- * Content-addressed {@link ContentVersionId}: SHA-256 of `body`,
388
- * lowercase hex, truncated to {@link VERSION_HEX_LENGTH}. Same body
389
- * bytes ⇒ same ContentVersionId — the property `Writer.commit`
390
- * relies on for idempotent replay (a crash-recovery rewrite of the
391
- * same logical value produces the same content key the manifest
392
- * already referenced).
393
- *
394
- * Async because {@link crypto.subtle.digest} returns an `ArrayBuffer`
395
- * via Promise. Workers and browsers both expose `crypto.subtle`
396
- * synchronously enough that the await fits naturally in the write
397
- * pipeline.
398
- *
399
- * @see docs/spec/log-entry-shape.md §"Content body layout"
400
- */
401
- const versionFromContent = async (body) => {
402
- const view = new Uint8Array(body.byteLength);
403
- view.set(body);
404
- const digest = await crypto.subtle.digest("SHA-256", view);
405
- const bytes = new Uint8Array(digest);
406
- let hex = "";
407
- for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
408
- return hex.slice(0, VERSION_HEX_LENGTH);
409
- };
410
- //#endregion
411
- //#region packages/protocol/src/snapshot-hash.ts
412
- /**
413
- * SHA-256 of `bytes` as a 64-char lowercase hex string. Used to seal
414
- * snapshot filenames so a crashed mid-PUT can't produce a body that
415
- * readers consume as truth: the filename embeds the hash; readers
416
- * recompute on load and reject any mismatch as "file missing."
417
- *
418
- * Distinct from {@link versionFromContent} (truncated to 32 chars for
419
- * content keys) — snapshot bodies are larger and longer-lived;
420
- * 256-bit collision resistance matters here.
421
- */
422
- const snapshotHash = async (bytes) => {
423
- const view = new Uint8Array(bytes.byteLength);
424
- view.set(bytes);
425
- const digest = await crypto.subtle.digest("SHA-256", view);
426
- const out = new Uint8Array(digest);
427
- let hex = "";
428
- for (let i = 0; i < out.length; i++) hex += out[i].toString(16).padStart(2, "0");
429
- return hex;
430
- };
431
- //#endregion
432
- //#region packages/server/src/indexes.ts
433
- /**
434
- * Secondary indexes — declarative collection-config-driven
435
- * index entries that the writer emits inside the same CAS fence as
436
- * the log entry and content body.
437
- *
438
- * The {@link IndexDefinition} TYPE lives in `@baerly/protocol`
439
- * (cross-platform). This module owns the runtime helpers that
440
- * operate on that shape:
441
- *
442
- * - {@link validateIndexDefinition} — synchronous schema check
443
- * for path-segment safety; thrown at `Writer` construction.
444
- * - {@link encodeIndexValue} — value-order-preserving base-32 of a
445
- * type-tagged byte stream (null/bool tag-only, numbers as sortable
446
- * IEEE 754, strings as raw UTF-8, objects as `JSON.stringify`
447
- * bytes for equality only).
448
- * - {@link indexKeyFor} / {@link indexKeyPrefix} — the wire-key
449
- * shape consumed by the writer's index PUTs and the rebuild
450
- * command's idempotent reconciliation.
451
- * - {@link projectIndexValues} / {@link allIndexKeysFor} — pure
452
- * projections from a doc body to the set of index keys it
453
- * produces under a collection's declared indexes.
454
- *
455
- * Wire shape (single-field):
456
- *
457
- * `<logPrefix>/index/<indexName>/<value-b32>/<docId>.json`
458
- *
459
- * Wire shape (composite — accepted by the encoder, not consulted by
460
- * the read path today):
461
- *
462
- * `<logPrefix>/index/<indexName>/<a-b32>/<b-b32>/<docId>.json`
463
- *
464
- * Body is zero bytes. Each entry is a fact ("doc `<docId>` has
465
- * `<field> = <value>`"), not data. Readers list the prefix, extract
466
- * the doc id from each key, then issue a content GET on each.
467
- *
468
- * Encoding is RFC-4648 base-32 (lowercase alphabet `[0-9a-v]`,
469
- * matching `packages/protocol/src/log.ts:str2uintDesc` style) on a
470
- * type-tagged byte stream (see {@link encodeIndexValue}) so that:
471
- *
472
- * - String "5" and number 5 produce distinct encodings
473
- * (type-tag prefix keeps the slots disjoint).
474
- * - Equal-by-value inputs produce byte-equal segments.
475
- * - Lex order under storage `list(prefix)` matches value order:
476
- * `null < false < true < number < string < object`, with
477
- * numeric values ordered by IEEE 754 magnitude (range walks
478
- * and `$in` walks over numeric fields are first-class — no
479
- * planner fall-back to full-scan).
480
- *
481
- * Locked: single-field indexes only on the read path. Composite
482
- * shape is documented and reserved (the path encoder accepts it).
483
- *
484
- * @see docs/spec/sync-protocol.md — fence model these PUTs land
485
- * inside (between log PUT and `current.json` CAS-advance).
486
- */
487
- /** Path-safe segment name. */
488
- const INDEX_NAME_RE = /^[a-z_][a-z0-9_]*$/;
489
- /**
490
- * Lowercase base-32 alphabet, RFC 4648 variant matching the
491
- * `packages/protocol/src/log.ts:str2uintDesc` style (`[0-9a-v]`).
492
- * Lex-order-preserving under storage `list(prefix)` semantics.
493
- */
494
- const B32_ALPHABET = "0123456789abcdefghijklmnopqrstuv";
495
- /**
496
- * Reject malformed {@link IndexDefinition} shapes synchronously.
497
- * Thrown at writer construction so a config typo trips before any
498
- * write lands.
499
- *
500
- * @throws BaerlyError code="SchemaError" — `name` doesn't match
501
- * `/^[a-z_][a-z0-9_]*$/`; `on` is the empty string or empty
502
- * array.
503
- */
504
- const validateIndexDefinition = (def) => {
505
- if (!INDEX_NAME_RE.test(def.name)) throw new BaerlyError("SchemaError", `index.name must match /^[a-z_][a-z0-9_]*$/; got ${JSON.stringify(def.name)}`);
506
- if (typeof def.on === "string") {
507
- if (def.on.length === 0) throw new BaerlyError("SchemaError", `index ${def.name}.on must be non-empty`);
508
- } else if (def.on.length === 0) throw new BaerlyError("SchemaError", `index ${def.name}.on must be non-empty array`);
509
- if (def.predicate !== void 0) try {
510
- validateWire(def.predicate);
511
- } catch (error) {
512
- if (error instanceof BaerlyError) throw new BaerlyError("SchemaError", `index ${def.name}.predicate is invalid: ${error.message}`, error);
513
- throw error;
514
- }
515
- };
516
- /**
517
- * Type-tag bytes for the value-order-preserving wire format. The
518
- * tag is the LEADING byte of the encoded payload; the values are
519
- * picked so the type order under byte-wise lex is
520
- * `null < false < true < number < string < object`.
521
- *
522
- * | Type | Byte-prefix | Payload |
523
- * |---------|-------------|----------------------------------------------------|
524
- * | null | 0x10 | (none) |
525
- * | false | 0x20 | (none) |
526
- * | true | 0x21 | (none) |
527
- * | number | 0x30 | 8-byte sortable big-endian IEEE 754 |
528
- * | string | 0x40 | UTF-8 bytes of the string (no quotes, no escapes) |
529
- * | object | 0x50 | UTF-8 bytes of `JSON.stringify(v)` |
530
- *
531
- * Local to the encoder by design — these are wire shape, not
532
- * cross-package protocol constants (see `CLAUDE.md` § "Magic
533
- * values").
534
- */
535
- const TYPE_NULL = 16;
536
- const TYPE_FALSE = 32;
537
- const TYPE_TRUE = 33;
538
- const TYPE_NUMBER = 48;
539
- const TYPE_STRING = 64;
540
- const TYPE_OBJECT = 80;
541
- /**
542
- * Encode a JS double as an 8-byte big-endian sortable IEEE 754
543
- * payload. Byte-wise lex order on the result matches numeric order
544
- * across all finite doubles plus `±Infinity`:
545
- *
546
- * 1. Get the 8-byte big-endian view of the double.
547
- * 2. If the sign bit is `0` (zero or positive), flip the sign bit
548
- * (XOR `0x80` on byte 0) so positives sort above negatives.
549
- * 3. If the sign bit is `1` (negative), flip every bit in all 8
550
- * bytes so more-negative sorts lower.
551
- *
552
- * `NaN` has no order-preserving slot and is rejected — see the
553
- * `encodeIndexValue` JSDoc for the wire-contract rationale.
554
- * `-0` and `+0` collapse because the `n === 0 ? 0 : n` coercion below
555
- * forces both into the positive-zero branch before `setFloat64`.
556
- */
557
- const encodeNumberPayload = (n) => {
558
- if (Number.isNaN(n)) throw new BaerlyError("SchemaError", `encodeIndexValue: NaN is not indexable (the byte encoding has no order-preserving slot for it)`);
559
- const buf = /* @__PURE__ */ new ArrayBuffer(8);
560
- new DataView(buf).setFloat64(0, n === 0 ? 0 : n, false);
561
- const bytes = new Uint8Array(buf);
562
- if ((bytes[0] & 128) === 0) bytes[0] = bytes[0] ^ 128;
563
- else for (let i = 0; i < 8; i++) bytes[i] = bytes[i] ^ 255;
564
- return bytes;
565
- };
566
- /**
567
- * Compose the typed byte stream for one value. The leading byte is
568
- * the type tag (see {@link TYPE_NULL} et al.); the payload shape is
569
- * type-dependent. Strings are emitted as their raw UTF-8 bytes (no
570
- * JSON quoting / escaping) so byte-wise lex order on encoded strings
571
- * matches byte-wise lex order on the source UTF-8. Objects fall back
572
- * to `JSON.stringify` for equality only.
573
- */
574
- const encodeBytes = (v) => {
575
- if (v === null || v === void 0) return new Uint8Array([TYPE_NULL]);
576
- if (v === false) return new Uint8Array([TYPE_FALSE]);
577
- if (v === true) return new Uint8Array([TYPE_TRUE]);
578
- if (typeof v === "number") {
579
- const payload = encodeNumberPayload(v);
580
- const out = new Uint8Array(1 + payload.length);
581
- out[0] = TYPE_NUMBER;
582
- out.set(payload, 1);
583
- return out;
584
- }
585
- if (typeof v === "string") {
586
- const utf8 = new TextEncoder().encode(v);
587
- const out = new Uint8Array(1 + utf8.length);
588
- out[0] = TYPE_STRING;
589
- out.set(utf8, 1);
590
- return out;
591
- }
592
- const utf8 = encodeJsonBytes(v);
593
- const out = new Uint8Array(1 + utf8.length);
594
- out[0] = TYPE_OBJECT;
595
- out.set(utf8, 1);
596
- return out;
597
- };
598
- /**
599
- * Encode an arbitrary `DocumentValue` value as a path-safe segment.
600
- *
601
- * Type-tagged byte stream, base-32-encoded for path safety. Lex
602
- * order on encoded bytes matches:
603
- *
604
- * - **Type order**: `null < false < true < number < string < object`.
605
- * - **Within numbers**: IEEE 754 numeric order (sortable
606
- * big-endian payload, sign-bit-flipped or all-bits-flipped).
607
- * `-Infinity` sorts lowest, `+Infinity` highest.
608
- * - **Within strings**: UTF-8 byte order.
609
- * - **Within objects**: byte-equality only (still
610
- * `JSON.stringify`-insertion-order dependent).
611
- *
612
- * Numbers ARE range-safe under this encoder — `9` sorts below `10`
613
- * as expected. The query planner's old
614
- * `numeric-range-on-byte-encoder` guard has been removed; range
615
- * walks and `$in` walks over numeric fields are routed normally.
616
- *
617
- * `NaN` throws `BaerlyError{code:"SchemaError"}` at write time —
618
- * the byte encoding has no order-preserving slot for it, and a
619
- * silent collapse to the `null` key (as the prior
620
- * `JSON.stringify`-based encoder did, since
621
- * `JSON.stringify(NaN) === "null"`) is a worse failure mode than
622
- * a loud reject.
623
- *
624
- * `-0` and `+0` collapse to the same encoding.
625
- *
626
- * Equal-by-value inputs (e.g. two `{a:1, b:2}` objects with the
627
- * same key insertion order) produce byte-equal segments;
628
- * structurally-different but visually-similar inputs (`"5"` vs `5`)
629
- * are kept apart by the type-tag prefix.
630
- *
631
- * String ranges remain safe: `"2026-05-13" < "2026-05-14"`
632
- * byte-wise matches semantic order. ISO 8601 timestamps,
633
- * alphabetical priorities like `"p1"/"p2"/"p3"`, and any
634
- * fixed-width string encoding are usable as range-walked indexed
635
- * fields.
636
- */
637
- const encodeIndexValue = (v) => {
638
- const bytes = encodeBytes(v);
639
- let out = "";
640
- let bits = 0;
641
- let value = 0;
642
- for (const b of bytes) {
643
- value = value << 8 | b;
644
- bits += 8;
645
- while (bits >= 5) {
646
- bits -= 5;
647
- out += B32_ALPHABET[value >> bits & 31];
648
- }
649
- }
650
- if (bits > 0) out += B32_ALPHABET[value << 5 - bits & 31];
651
- return out;
652
- };
653
- /**
654
- * Storage `list(prefix)` boundary for every entry under one index
655
- * of a collection: `<logPrefix>/index/<name>/`. Used by the rebuild
656
- * command's reconciliation walk and by the read-path index hint.
657
- */
658
- const indexKeyPrefix = (logPrefix, indexName) => `${logPrefix}/index/${indexName}/`;
659
- /**
660
- * Build the per-doc index key for one `(def, values, docId)`.
661
- *
662
- * Single-field: `<logPrefix>/index/<name>/<v0-b32>/<docId>.json`.
663
- * Composite: `<logPrefix>/index/<name>/<v0-b32>/<v1-b32>/.../<docId>.json`.
664
- *
665
- * Composite shape is accepted but the read path today only
666
- * consults single-field entries.
667
- */
668
- const indexKeyFor = (logPrefix, def, values, docId) => {
669
- const segments = values.map(encodeIndexValue).join("/");
670
- return `${logPrefix}/index/${def.name}/${segments}/${docId}.json`;
671
- };
672
- /**
673
- * Project the value tuple a doc body produces under one index
674
- * definition. Returns `undefined` when any indexed field is
675
- * null / undefined / missing — no index entry for that doc under
676
- * that index (SQL "NULL values don't enter the index" semantics).
677
- *
678
- * @throws BaerlyError code="SchemaError" — `on` contains a dotted
679
- * path, or the indexed field's value is an array. Both restrictions
680
- * are pre-launch; multi-value (array) indexes are a follow-up.
681
- */
682
- const projectIndexValues = (def, body) => {
683
- if (body === void 0) return;
684
- const fields = typeof def.on === "string" ? [def.on] : def.on;
685
- const values = [];
686
- for (const field of fields) {
687
- if (field.includes(".")) throw new BaerlyError("SchemaError", `index ${def.name}: dotted-path "on" fields not yet supported (got ${JSON.stringify(field)})`);
688
- const v = body[field];
689
- if (v === null || v === void 0) return;
690
- if (Array.isArray(v)) throw new BaerlyError("SchemaError", `index ${def.name}: cannot index array field "${field}" — multi-value indexes are not supported yet`);
691
- values.push(v);
692
- }
693
- return values;
694
- };
695
- /**
696
- * Compute the full index-key set a single doc produces under every
697
- * declared index of its collection. Skips indexes whose projection
698
- * yields `undefined` (null/missing indexed field). Used by both
699
- * the writer (to PUT new keys) and the rebuild command (to compute
700
- * the expected key set across the live doc map).
701
- *
702
- * Filter-aware (T4): when `def.predicate !== undefined`, the doc
703
- * must satisfy `matchesWire(def.predicate, body)` or the def contributes
704
- * zero keys. The writer's diff `oldKeys` vs `newKeys` then covers
705
- * all four U-quadrants automatically — see the JSDoc on
706
- * `writer.ts` above the index-emission block. `body ===
707
- * undefined` short-circuits ahead of the filter check (no keys for
708
- * an unknown pre-image, regardless of filter), preserving the prior
709
- * D-quadrant behaviour.
710
- */
711
- const allIndexKeysFor = (logPrefix, defs, body, docId) => {
712
- const keys = [];
713
- for (const def of defs) {
714
- if (def.predicate !== void 0 && body !== void 0) {
715
- if (!matchesWire(def.predicate, body)) continue;
716
- }
717
- const values = projectIndexValues(def, body);
718
- if (values !== void 0) keys.push(indexKeyFor(logPrefix, def, values, docId));
719
- }
720
- return keys;
721
- };
722
- //#endregion
723
- //#region packages/server/src/log-walk.ts
724
- /**
725
- * Shared log-walk primitives consumed by the read path (`query.ts`),
726
- * the compactor (`compactor.ts`), and the optional integrity walk in
727
- * `Writer.#singleAttemptCommit` (`writer.ts`).
728
- *
729
- * Two operations: read one log entry, or walk a contiguous range of
730
- * log entries with bounded parallelism. Each kernel call site
731
- * previously inlined the same range-build + unbounded `Promise.all`
732
- * pattern; on a free-tier collection where the compactor lags the
733
- * tail to 50-100 entries, that fans out 50-100 concurrent GETs per
734
- * call — and a contended writer multiplies that by the CAS retry
735
- * budget. `walkLogRange` caps concurrency at
736
- * {@link MAX_PARALLEL_LOG_READS} so a single call costs at most that
737
- * many simultaneous GETs against the storage backend.
738
- *
739
- * Order invariant: results are returned in seq order regardless of
740
- * resolution order. The read-side fold is order-sensitive (`U` then
741
- * `D` on the same doc must apply in that order); callers may iterate
742
- * the returned array as-is.
743
- *
744
- * Signal invariant: when the caller's `AbortSignal` fires, no further
745
- * chunks dispatch. In-flight reads see the signal via the underlying
746
- * `Storage.get` call.
747
- */
748
- /**
749
- * Fetch a single log entry. Centralises the "missing entry inside the
750
- * visible log range is a protocol-invariant violation" rule used by
751
- * every caller.
752
- *
753
- * @throws BaerlyError code="Internal" when the key resolves to no
754
- * body — a hole inside `[log_seq_start, next_seq)` is a corruption
755
- * the kernel can't continue past.
756
- * @throws BaerlyError code="InvalidResponse" when the body isn't
757
- * valid JSON.
758
- */
759
- const readLogEntry = async (storage, key, opts) => {
760
- const got = await storage.get(key, opts?.signal !== void 0 ? { signal: opts.signal } : void 0);
761
- if (got === null) throw new BaerlyError("Internal", `log-walk: missing log entry at ${key}; protocol invariant violation`);
762
- try {
763
- return decodeJsonBytes(got.body);
764
- } catch (error) {
765
- throw new BaerlyError("InvalidResponse", `log-walk: malformed log entry at ${key}`, error);
766
- }
767
- };
768
- /**
769
- * Walk `[fromSeq, toSeqExclusive)` of `${logPrefix}/log/<seq>.json`
770
- * in chunks of {@link MAX_PARALLEL_LOG_READS} concurrent GETs.
771
- * Returns the materialised entries in seq order.
772
- *
773
- * Empty range (`fromSeq >= toSeqExclusive`) returns `[]` and issues
774
- * zero GETs.
775
- *
776
- * Same error semantics as {@link readLogEntry}: a missing entry
777
- * throws `Internal`, a malformed body throws `InvalidResponse`.
778
- */
779
- const walkLogRange = async (storage, logPrefix, fromSeq, toSeqExclusive, opts) => {
780
- if (fromSeq >= toSeqExclusive) return [];
781
- const total = toSeqExclusive - fromSeq;
782
- const out = Array.from({ length: total });
783
- for (let chunkStart = 0; chunkStart < total; chunkStart += 16) {
784
- opts?.signal?.throwIfAborted();
785
- const chunkEnd = Math.min(chunkStart + 16, total);
786
- const promises = [];
787
- for (let i = chunkStart; i < chunkEnd; i++) {
788
- const seq = fromSeq + i;
789
- promises.push(readLogEntry(storage, `${logPrefix}/log/${seq}.json`, opts));
790
- }
791
- const results = await Promise.all(promises);
792
- for (let i = 0; i < results.length; i++) out[chunkStart + i] = results[i];
793
- }
794
- return out;
795
- };
796
- /**
797
- * Fold a sequence of `LogEntry` records onto a doc-id-keyed map,
798
- * applying the protocol's per-doc-replace semantics:
799
- *
800
- * - `I` / `U`: when `entry.new !== undefined`, set
801
- * `map.set(entry.doc_id, entry.new)`. Entries with `new ===
802
- * undefined` (the partial-merge writer's future patch-only shape)
803
- * are ignored — today's writer always emits `new`, so this is a
804
- * forward-compat guard, not a live branch.
805
- * - `D`: tombstone — `map.delete(entry.doc_id)`.
806
- * - `T` / `M`: ignored. `T` (TRUNCATE) is not yet wired; `M`
807
- * (MESSAGE) is a marker. The emitter never produces them today.
808
- *
809
- * Entries whose `collection` does not match `opts.collection`, or
810
- * whose `doc_id` is `undefined`, are skipped. When
811
- * `opts.docIdFilter` is provided, only entries whose `doc_id` is
812
- * present in the filter set are folded — used by the index-walk
813
- * read path to scope the fold to the docs the planner already
814
- * resolved.
815
- *
816
- * This is the canonical fold used by the read path
817
- * (`query.ts`) and the index reconciler (`rebuild-index.ts`).
818
- * Centralising it keeps the
819
- * "ignore T/M; straight `set` on I/U; tombstone on D" protocol
820
- * invariant in one place.
821
- *
822
- * @see ../../../docs/spec/sync-protocol.md
823
- */
824
- const foldLogEntriesOnto = (map, entries, opts) => {
825
- const { collection, docIdFilter } = opts;
826
- for (const entry of entries) {
827
- if (entry.collection !== collection) continue;
828
- if (entry.doc_id === void 0) continue;
829
- if (docIdFilter !== void 0 && !docIdFilter.has(entry.doc_id)) continue;
830
- switch (entry.op) {
831
- case "I":
832
- case "U":
833
- if (entry.new === void 0) continue;
834
- map.set(entry.doc_id, entry.new);
835
- break;
836
- case "D":
837
- map.delete(entry.doc_id);
838
- break;
839
- case "T":
840
- case "M": break;
841
- }
842
- }
843
- };
844
- const MAX_SEQ = 10 ** 12 - 1;
845
- /**
846
- * Build the on-bucket key for a snapshot file. `sha256` must be the
847
- * lowercase hex digest of the canonical body
848
- * ({@link encodeSnapshotBody}); the filename embeds it so a crashed
849
- * mid-PUT body that doesn't match its own filename hash is rejected
850
- * by readers as "missing."
851
- *
852
- * @throws BaerlyError code="InvalidConfig" — `minSeq`/`maxSeq` are
853
- * out of range or `sha256` is not 64 hex chars.
854
- */
855
- const snapshotKey = (collectionPrefix, minSeq, maxSeq, sha256) => {
856
- if (minSeq < 0 || maxSeq < 0 || minSeq > maxSeq || maxSeq > MAX_SEQ) throw new BaerlyError("InvalidConfig", `snapshotKey: invalid range [${minSeq}, ${maxSeq})`);
857
- if (!/^[0-9a-f]{64}$/.test(sha256)) throw new BaerlyError("InvalidConfig", "snapshotKey: sha256 must be 64 hex chars");
858
- const pad = (n) => n.toString().padStart(12, "0");
859
- return `${collectionPrefix}/snapshot/L9/${pad(minSeq)}-${pad(maxSeq)}-${sha256}.json`;
860
- };
861
- /**
862
- * Canonical byte encoding of a {@link SnapshotBody}. Only the
863
- * compactor produces snapshots, and only this function does the
864
- * serialisation — so the byte output is deterministic for a given
865
- * `SnapshotBody` (identical input ⇒ identical bytes ⇒ identical
866
- * filename hash).
867
- */
868
- const encodeSnapshotBody = (s) => encodeJsonBytes(s);
869
- /**
870
- * Load a snapshot file as a `Map<_id, DocumentData>`. Verifies the
871
- * body hash against the filename, checks the schema version, and
872
- * cross-checks `body.collection` against the caller's expectation.
873
- *
874
- * @example
875
- * ```ts
876
- * import { loadSnapshotAsMap } from "@gusto/baerly-storage";
877
- *
878
- * const map =
879
- * srcCurrent.snapshot === null
880
- * ? new Map<string, DocumentData>()
881
- * : await loadSnapshotAsMap(src.storage, srcCurrent.snapshot, "tickets");
882
- * ```
883
- *
884
- * @throws BaerlyError code="Internal" — pointer resolves to no body,
885
- * or the body's SHA-256 doesn't match the hash embedded in the
886
- * filename. (Protocol invariant violation; a corrupted snapshot
887
- * the reader cannot continue past.)
888
- * @throws BaerlyError code="InvalidResponse" — body isn't valid JSON,
889
- * isn't an object, has an unsupported `schema_version`, or carries a
890
- * `collection` that doesn't match `expectedCollection`.
891
- */
892
- const loadSnapshotAsMap = async (storage, key, expectedCollection, signal) => {
893
- const got = await storage.get(key, signal !== void 0 ? { signal } : void 0);
894
- if (got === null) throw new BaerlyError("Internal", `compact: snapshot pointer ${key} resolves to no body; protocol violation`);
895
- const filename = key.slice(key.lastIndexOf("/") + 1).replace(/\.json$/, "");
896
- const lastDash = filename.lastIndexOf("-");
897
- const expectedHash = filename.slice(lastDash + 1);
898
- const actualHash = await snapshotHash(got.body);
899
- if (actualHash !== expectedHash) throw new BaerlyError("Internal", `compact: snapshot ${key} body hash mismatch (got ${actualHash}); protocol violation`);
900
- let parsed;
901
- try {
902
- parsed = decodeJsonBytes(got.body);
903
- } catch (error) {
904
- throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} body is not valid JSON`, error);
905
- }
906
- if (parsed === null || typeof parsed !== "object") throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} body is not an object`);
907
- const body = parsed;
908
- if (body.schema_version !== 1) throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} has unsupported schema_version ${String(body.schema_version)}`);
909
- if (body.collection !== expectedCollection) throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} carries collection ${body.collection}, expected ${expectedCollection}`);
910
- const out = /* @__PURE__ */ new Map();
911
- for (const row of body.docs) out.set(row._id, row.body);
912
- return out;
913
- };
914
- //#endregion
915
- export { readLogEntry as a, encodeIndexValue as c, snapshotHash as d, versionFromContent as f, deepEqualDocumentValue as g, matchesWire as h, foldLogEntriesOnto as i, indexKeyPrefix as l, assertWireSatisfiable as m, loadSnapshotAsMap as n, walkLogRange as o, validateWire as p, snapshotKey as r, allIndexKeysFor as s, encodeSnapshotBody as t, validateIndexDefinition as u };
916
-
917
- //# sourceMappingURL=snapshot-z_N9hpTe.js.map