@gusto/baerly-storage 0.1.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 (115) hide show
  1. package/README.md +97 -0
  2. package/dist/API.md +850 -0
  3. package/dist/app-config-Cb5dO2s9.d.ts +480 -0
  4. package/dist/app-config.d.ts +2 -0
  5. package/dist/app-config.js +8 -0
  6. package/dist/app-config.js.map +1 -0
  7. package/dist/auth.d.ts +237 -0
  8. package/dist/auth.js +1335 -0
  9. package/dist/auth.js.map +1 -0
  10. package/dist/baerly.js +761 -0
  11. package/dist/baerly.js.map +1 -0
  12. package/dist/bucket-uri-BrDEYvzy.js +4922 -0
  13. package/dist/bucket-uri-BrDEYvzy.js.map +1 -0
  14. package/dist/chunk-EAsCxrDo.js +14 -0
  15. package/dist/client-BLf3Ae5s.d.ts +233 -0
  16. package/dist/client-react.d.ts +131 -0
  17. package/dist/client-react.js +559 -0
  18. package/dist/client-react.js.map +1 -0
  19. package/dist/client.d.ts +4 -0
  20. package/dist/client.js +160 -0
  21. package/dist/client.js.map +1 -0
  22. package/dist/cloudflare-CINJPKCW.js +911 -0
  23. package/dist/cloudflare-CINJPKCW.js.map +1 -0
  24. package/dist/cloudflare.d.ts +211 -0
  25. package/dist/cloudflare.js +445 -0
  26. package/dist/cloudflare.js.map +1 -0
  27. package/dist/config-Bsg8wgwo.js +198 -0
  28. package/dist/config-Bsg8wgwo.js.map +1 -0
  29. package/dist/context-Oj7ffwD-.js +187 -0
  30. package/dist/context-Oj7ffwD-.js.map +1 -0
  31. package/dist/cost-B1WiZxlf.js +203 -0
  32. package/dist/cost-B1WiZxlf.js.map +1 -0
  33. package/dist/current-json-BkatBzF7.js +252 -0
  34. package/dist/current-json-BkatBzF7.js.map +1 -0
  35. package/dist/db-D62JguBc.d.ts +336 -0
  36. package/dist/deploy-BB-wqbhf.js +83 -0
  37. package/dist/deploy-BB-wqbhf.js.map +1 -0
  38. package/dist/dev-banner-CWHIk8tH.d.ts +26 -0
  39. package/dist/dev-vite.d.ts +146 -0
  40. package/dist/dev-vite.js +223 -0
  41. package/dist/dev-vite.js.map +1 -0
  42. package/dist/dev.d.ts +3 -0
  43. package/dist/dev.js +2 -0
  44. package/dist/doctor-B8h9GCN9.js +331 -0
  45. package/dist/doctor-B8h9GCN9.js.map +1 -0
  46. package/dist/dump-BHo_sIMZ.js +116 -0
  47. package/dist/dump-BHo_sIMZ.js.map +1 -0
  48. package/dist/errors-DOdL95kK.js +58 -0
  49. package/dist/errors-DOdL95kK.js.map +1 -0
  50. package/dist/export-Dz2PZKSR.js +423 -0
  51. package/dist/export-Dz2PZKSR.js.map +1 -0
  52. package/dist/fsck-DEz9lyCy.js +293 -0
  53. package/dist/fsck-DEz9lyCy.js.map +1 -0
  54. package/dist/http-CjUO1Bec.js +1756 -0
  55. package/dist/http-CjUO1Bec.js.map +1 -0
  56. package/dist/http.d.ts +1619 -0
  57. package/dist/http.js +2 -0
  58. package/dist/index-BGC-ENnj.d.ts +1065 -0
  59. package/dist/index-BYv0hb8M.d.ts +1457 -0
  60. package/dist/index-BquQkhJi.d.ts +112 -0
  61. package/dist/index-COsQ-Mlz.d.ts +146 -0
  62. package/dist/index.d.ts +6 -0
  63. package/dist/index.js +6 -0
  64. package/dist/indexes-BXn7a06a.js +297 -0
  65. package/dist/indexes-BXn7a06a.js.map +1 -0
  66. package/dist/indexes-DwOXkn1Y.d.ts +22 -0
  67. package/dist/inspect-x02aFWnh.js +149 -0
  68. package/dist/inspect-x02aFWnh.js.map +1 -0
  69. package/dist/log-walk-DIru96UT.js +260 -0
  70. package/dist/log-walk-DIru96UT.js.map +1 -0
  71. package/dist/maintenance-Bn6ul9aV.js +758 -0
  72. package/dist/maintenance-Bn6ul9aV.js.map +1 -0
  73. package/dist/maintenance.d.ts +323 -0
  74. package/dist/maintenance.js +2 -0
  75. package/dist/node.d.ts +422 -0
  76. package/dist/node.js +2 -0
  77. package/dist/normalize-XWY25_sG.js +133 -0
  78. package/dist/normalize-XWY25_sG.js.map +1 -0
  79. package/dist/observability-2IDYRuZK.js +2333 -0
  80. package/dist/observability-2IDYRuZK.js.map +1 -0
  81. package/dist/observability.d.ts +3 -0
  82. package/dist/observability.js +3 -0
  83. package/dist/plan-Cs17VqjU.js +224 -0
  84. package/dist/plan-Cs17VqjU.js.map +1 -0
  85. package/dist/query-DcSbFLJt.js +1880 -0
  86. package/dist/query-DcSbFLJt.js.map +1 -0
  87. package/dist/rebuild-index-C5gTXryd.js +119 -0
  88. package/dist/rebuild-index-C5gTXryd.js.map +1 -0
  89. package/dist/rebuild-index-DwXM0WfA.js +104 -0
  90. package/dist/rebuild-index-DwXM0WfA.js.map +1 -0
  91. package/dist/request-BEF_OvMh.js +72 -0
  92. package/dist/request-BEF_OvMh.js.map +1 -0
  93. package/dist/restore-CbKVMMpm.js +847 -0
  94. package/dist/restore-CbKVMMpm.js.map +1 -0
  95. package/dist/shared-secret-BJdSwpgw.js +71 -0
  96. package/dist/shared-secret-BJdSwpgw.js.map +1 -0
  97. package/dist/snapshot-D7C4_FSl.js +71 -0
  98. package/dist/snapshot-D7C4_FSl.js.map +1 -0
  99. package/dist/snapshot-z_N9hpTe.js +917 -0
  100. package/dist/snapshot-z_N9hpTe.js.map +1 -0
  101. package/dist/src-Chafbw8r.js +522 -0
  102. package/dist/src-Chafbw8r.js.map +1 -0
  103. package/dist/src-DyET_VPP.js +6199 -0
  104. package/dist/src-DyET_VPP.js.map +1 -0
  105. package/dist/src-n0Te1r98.js +352 -0
  106. package/dist/src-n0Te1r98.js.map +1 -0
  107. package/dist/subcommand-BWs6K7zb.js +110 -0
  108. package/dist/subcommand-BWs6K7zb.js.map +1 -0
  109. package/dist/usage-RVUQMLop.js +339 -0
  110. package/dist/usage-RVUQMLop.js.map +1 -0
  111. package/dist/validate-DhH1lO8I.js +377 -0
  112. package/dist/validate-DhH1lO8I.js.map +1 -0
  113. package/dist/wire-izfGZDvr.js +7 -0
  114. package/dist/wire-izfGZDvr.js.map +1 -0
  115. package/package.json +189 -0
@@ -0,0 +1,1880 @@
1
+ import { c as MANIFEST_POINTER_EMPTY_SNAPSHOT, f as decodeJsonBytes, i as FORBIDDEN_MERGE_KEYS, n as logSeqStartOf, p as encodeJsonBytes, r as readCurrentJson, t as createCurrentJson } from "./current-json-BkatBzF7.js";
2
+ import { t as BaerlyError } from "./errors-DOdL95kK.js";
3
+ import { a as readLogEntry, c as encodeIndexValue, f as versionFromContent, g as deepEqualDocumentValue, h as matchesWire, i as foldLogEntriesOnto, m as assertWireSatisfiable, n as loadSnapshotAsMap, o as walkLogRange, p as validateWire, s as allIndexKeysFor, u as validateIndexDefinition } from "./snapshot-z_N9hpTe.js";
4
+ import { t as normalizePredicateArg } from "./normalize-XWY25_sG.js";
5
+ import { i as noopMetricsRecorder, n as getCurrentContext } from "./context-Oj7ffwD-.js";
6
+ //#region packages/protocol/src/json.ts
7
+ const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
8
+ /**
9
+ * JSON Merge Patch (RFC 7396).
10
+ *
11
+ * Update `target` with a merge patch. Plain-object values recurse
12
+ * key-by-key; primitives, arrays, and type-mismatched values replace
13
+ * the target wholesale. A `null` value in `patch` deletes the key.
14
+ *
15
+ * RFC 7396 explicitly treats arrays as opaque values: an array in a
16
+ * patch replaces the target array — there is no element-wise merge.
17
+ */
18
+ function merge(target, patch) {
19
+ if (patch === void 0) return target;
20
+ if (patch === null) return;
21
+ if (!isPlainObject(patch)) return patch;
22
+ if (!isPlainObject(target)) return patch;
23
+ const combined = { ...target };
24
+ for (const key of Object.keys(patch)) {
25
+ if (FORBIDDEN_MERGE_KEYS.has(key)) continue;
26
+ if (patch[key] === null) delete combined[key];
27
+ else combined[key] = merge(target[key], patch[key]);
28
+ }
29
+ return combined;
30
+ }
31
+ //#endregion
32
+ //#region packages/protocol/src/query/merge.ts
33
+ /**
34
+ * AND-merge two validated wire predicates. Powers chained
35
+ * `Query<T>.where(...).where(...)`: each new clause set AND's with
36
+ * the existing wire by clause-list concatenation; the per-field
37
+ * satisfiability check runs across the combined list.
38
+ *
39
+ * Companion modules: `./validate.ts`, `./matches.ts`, `./wire.ts`.
40
+ */
41
+ /**
42
+ * AND-merge two validated wire predicates. The result accepts a
43
+ * document iff both `a` and `b` would accept it.
44
+ *
45
+ * Wire-level: clause lists concatenate. The per-field satisfiability
46
+ * check runs across the combined list, surfacing
47
+ * `BaerlyError{code:"UnsatisfiablePredicate"}` on empty residual
48
+ * intervals / empty `in()` intersections / `eq` outside the merged
49
+ * interval, and `BaerlyError{code:"InvalidConfig"}` on conflicting
50
+ * `eq` clauses for the same field (mirrors the pre-redesign
51
+ * conflict-on-shared-keys semantics).
52
+ *
53
+ * @example
54
+ * ```ts
55
+ * mergePredicateWires(
56
+ * { clauses: [{ op: "eq", field: "status", value: "open" }] },
57
+ * { clauses: [{ op: "eq", field: "priority", value: "p1" }] },
58
+ * );
59
+ * // → { clauses: [
60
+ * // { op: "eq", field: "status", value: "open" },
61
+ * // { op: "eq", field: "priority", value: "p1" },
62
+ * // ] }
63
+ *
64
+ * mergePredicateWires(
65
+ * { clauses: [{ op: "eq", field: "status", value: "open" }] },
66
+ * { clauses: [{ op: "eq", field: "status", value: "closed" }] },
67
+ * );
68
+ * // throws BaerlyError{InvalidConfig}: conflicting equality clauses on "status"
69
+ *
70
+ * mergePredicateWires(
71
+ * { clauses: [{ op: "gt", field: "x", value: 10 }] },
72
+ * { clauses: [{ op: "lt", field: "x", value: 5 }] },
73
+ * );
74
+ * // throws BaerlyError{UnsatisfiablePredicate}: empty interval
75
+ * ```
76
+ */
77
+ const mergePredicateWires = (a, b) => {
78
+ const merged = { clauses: [...a.clauses, ...b.clauses] };
79
+ assertWireSatisfiable(merged);
80
+ return merged;
81
+ };
82
+ //#endregion
83
+ //#region packages/protocol/src/types.ts
84
+ /**
85
+ * Mint a fresh {@link UUID}. The cast lives here so callers don't sprinkle
86
+ * `<UUID>crypto.randomUUID()` throughout the codebase.
87
+ */
88
+ const uuid = () => crypto.randomUUID();
89
+ /**
90
+ * Mint a UUIDv7 — 48-bit Unix-millis prefix + 74 bits of randomness,
91
+ * formatted as a standard 8-4-4-4-12 UUID string per RFC 9562 §5.7.
92
+ * Lex-sortable by mint time, so it pairs well with object-storage
93
+ * list semantics. Returns a branded {@link UUID}.
94
+ *
95
+ * Uses `crypto.getRandomValues` which is universally available
96
+ * (Node 19+, Workerd, Bun, browsers).
97
+ *
98
+ * @example
99
+ * ```ts
100
+ * const id = uuidv7();
101
+ * // e.g. "01956cad-4cc8-7abc-9def-0123456789ab"
102
+ * ```
103
+ */
104
+ const uuidv7 = () => {
105
+ const millis = Date.now();
106
+ const rand = new Uint8Array(10);
107
+ crypto.getRandomValues(rand);
108
+ rand[0] = rand[0] & 15 | 112;
109
+ rand[2] = rand[2] & 63 | 128;
110
+ const millisHex = millis.toString(16).padStart(12, "0");
111
+ const b = Array.from(rand, (n) => n.toString(16).padStart(2, "0")).join("");
112
+ return `${millisHex.slice(0, 8)}-${millisHex.slice(8, 12)}-${b.slice(0, 4)}-${b.slice(4, 8)}-${b.slice(8, 20)}`;
113
+ };
114
+ /**
115
+ * Mint the trailing seq segment of an LSN (`<base32-time>_<sess>_<seq>`).
116
+ * `COUNT_BIT_WIDTH = 10` (matches `packages/protocol/src/log.ts:145`)
117
+ * gives a 2-char descending base-32 string with a domain of 0..1023.
118
+ *
119
+ * Used together with {@link timestamp} (the descending base-32
120
+ * encoding of millis-since-epoch). See {@link uint2strDesc} for the
121
+ * lex-reversal property both rely on.
122
+ */
123
+ const countKey = (number) => uint2strDesc(number, 10);
124
+ const uint2str = (num, bits) => {
125
+ const maxBase32Length = Math.ceil(bits / 5);
126
+ return num.toString(32).padStart(maxBase32Length, "0");
127
+ };
128
+ /**
129
+ * Lex-reversed base-32 encoder for an unsigned integer in `[0, 2^bits)`.
130
+ * Pads to `Math.ceil(bits/5)` chars so all values in the domain compare
131
+ * lex against each other.
132
+ *
133
+ * **Order-reversal property:** for any pair of integers `a < b` (with
134
+ * `a, b ∈ [0, 2^bits)`), `uint2strDesc(a, bits) > uint2strDesc(b, bits)`
135
+ * lexicographically. Composed into an LSN of shape
136
+ * `<base32-time>_<session>_<seq>` (where both `<base32-time>` and
137
+ * `<seq>` use this encoder), a forward `Storage.list(prefix)`
138
+ * returns log entries in reverse-causal order — newer entries first.
139
+ *
140
+ * This is the structural property the read path leans on:
141
+ * `ListObjectsV2` is forward-only on S3, but the descending encoding
142
+ * makes "fetch the K newest entries" a single bounded LIST with
143
+ * `maxKeys=K` instead of a full-population LIST + in-memory reverse.
144
+ *
145
+ * Behaviourally verified across randomized populations in
146
+ * `packages/protocol/src/lsn-reverse-list.test.ts`. Quantified
147
+ * bytes-listed reduction is in
148
+ * `docs/spec/attachments/lsn-reverse-walk-baseline.json`
149
+ * (run `pnpm bench:lsn-reverse-walk` to reproduce). Spec rationale:
150
+ * `docs/spec/sync-protocol.md` §"Subtleties of the manifest key".
151
+ */
152
+ const uint2strDesc = (num, bits) => {
153
+ return uint2str(Math.pow(2, bits) - 1 - num, bits);
154
+ };
155
+ const str2uintDesc = (str, bits) => {
156
+ return Math.pow(2, bits) - 1 - parseInt(str, 32);
157
+ };
158
+ //#endregion
159
+ //#region packages/protocol/src/time.ts
160
+ const timestamp = (epoch = 0) => uint2strDesc(epoch, 42);
161
+ /**
162
+ * Delay for `ms` milliseconds, with optional cancellation. If
163
+ * `signal` aborts before the delay elapses, the returned promise
164
+ * rejects with `signal.reason`. Used by `S3HttpStorage`'s retry
165
+ * loop so shutdown can interrupt an in-flight backoff instead of
166
+ * waiting for it to complete.
167
+ */
168
+ const delay = (ms, signal) => new Promise((resolve, reject) => {
169
+ if (signal?.aborted) {
170
+ reject(signal.reason);
171
+ return;
172
+ }
173
+ const timer = setTimeout(resolve, ms);
174
+ signal?.addEventListener("abort", () => {
175
+ clearTimeout(timer);
176
+ reject(signal.reason);
177
+ }, { once: true });
178
+ });
179
+ //#endregion
180
+ //#region packages/protocol/src/log.ts
181
+ const COUNT_BIT_WIDTH = 10;
182
+ /**
183
+ * Extract the `session` and `seq` embedded in an `lsn` of shape
184
+ * `<base32-time>_<session>_<seq>`. The seq portion is decoded as a
185
+ * descending base-32 integer (matches `countKey` in `./types`).
186
+ *
187
+ * Use this at the `/v1/since` cursor-decoding boundary, where a
188
+ * client resumes from an opaque `SinceResponse.next_cursor` and no
189
+ * `LogEntry` is in scope. When iterating `LogEntry` records, read
190
+ * `entry.session` / `entry.seq` directly instead.
191
+ *
192
+ * Throws on malformed input; callers should pass only lsns minted
193
+ * by `Writer.commit` (see
194
+ * `packages/server/src/writer.ts`).
195
+ */
196
+ const lsnParts = (lsn) => {
197
+ const parts = lsn.split("_");
198
+ if (parts.length !== 3) throw new BaerlyError("InvalidResponse", `invalid lsn shape: ${lsn}`);
199
+ return {
200
+ session: parts[1],
201
+ seq: str2uintDesc(parts[2], COUNT_BIT_WIDTH)
202
+ };
203
+ };
204
+ //#endregion
205
+ //#region packages/server/src/log-conflict-adoption.ts
206
+ /**
207
+ * Decide whether the entry already at `/log/<seq>.json` is the
208
+ * writer's own prior in-flight attempt and may be adopted. Pure
209
+ * function; no I/O. The caller performs the GET (when the log PUT
210
+ * surfaces 412) and passes the read-back body in `ctx.existing`.
211
+ *
212
+ * @see {@link AdoptionDecision} for the return shape.
213
+ * @see The soundness invariant in this module's header docstring.
214
+ */
215
+ const tryAdoptOwnSessionLogEntry = (ctx) => {
216
+ if (ctx.batchSize !== 1) return {
217
+ adopt: false,
218
+ reason: "batch"
219
+ };
220
+ if (ctx.existing.session !== ctx.self.session) return {
221
+ adopt: false,
222
+ reason: "foreign-session"
223
+ };
224
+ if (ctx.existing.seq !== ctx.self.seq) return {
225
+ adopt: false,
226
+ reason: "wrong-seq"
227
+ };
228
+ return {
229
+ adopt: true,
230
+ entry: ctx.existing
231
+ };
232
+ };
233
+ //#endregion
234
+ //#region packages/server/src/writer.ts
235
+ /**
236
+ * `Writer` — stateless multi-instance write engine.
237
+ *
238
+ * Each {@link Writer.commit} call reads `current.json` FRESH from
239
+ * the bucket, mints the next {@link LogEntry}, PUTs the content body
240
+ * and the log entry, and CAS-advances `current.json` with `If-Match`.
241
+ * Up to {@link S3_REQUEST_MAX_RETRIES} attempts on contention before
242
+ * surfacing `BaerlyError{code:"Conflict"}`. The optional integrity
243
+ * walk over the live log tail is gated by
244
+ * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off
245
+ * — see the option's docstring).
246
+ *
247
+ * The instance carries no per-write cache: every commit re-reads
248
+ * `current.json`, so N stateless server instances writing the same
249
+ * tenant prefix contend at exactly one place — the conditional PUT
250
+ * on `current.json` — and one loses cleanly with a 412.
251
+ *
252
+ * **Manifest-first ordering is REVERSED relative to the legacy
253
+ * `src/syncer.ts` write loop.** Old loop: PUT manifest → PUT content
254
+ * → CAS. New loop: PUT content → PUT log entry → CAS-advance
255
+ * `current.json`. A crashed mid-loop writer leaves an unreferenced
256
+ * content body (no log entry points at it), not an orphan log entry
257
+ * with missing content. The compactor sweeps the orphan content
258
+ * later.
259
+ *
260
+ * **`LogEntry` shape.** Emitted entries follow the contract in
261
+ * `packages/protocol/src/log.ts` (see {@link LogEntry}) and
262
+ * `docs/spec/log-entry-shape.md`. The on-bucket key is
263
+ * `log/<seq>.json` (the integer `seq` is the load-bearing
264
+ * identifier; the `lsn` string is schema-only).
265
+ *
266
+ * @see docs/spec/sync-protocol.md for the protocol invariants this
267
+ * loop preserves.
268
+ * @see docs/spec/log-entry-shape.md for the per-field contract.
269
+ */
270
+ const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
271
+ const DEFAULT_INITIAL_BACKOFF_MS = 25;
272
+ const MAX_BACKOFF_MS = 1500;
273
+ const APPLICATION_JSON = "application/json";
274
+ /**
275
+ * Empty body for index entries. Each index entry is a fact ("doc
276
+ * `<docId>` has `<field> = <value>`"), not data — readers list the
277
+ * prefix, extract the doc id, then GET the content body separately.
278
+ * Pre-allocated module-level constant so every index PUT shares one
279
+ * zero-length buffer.
280
+ */
281
+ const EMPTY_BODY = new Uint8Array(0);
282
+ /**
283
+ * Stateless write engine for the multi-instance core.
284
+ *
285
+ * Construction is cheap and performs zero I/O — adapters build a
286
+ * fresh `Writer` per request and discard it. All real work
287
+ * happens in {@link commit}.
288
+ *
289
+ * @example
290
+ * ```ts
291
+ * import { Writer } from "@gusto/baerly-storage";
292
+ * import { MemoryStorage } from "@gusto/baerly-storage";
293
+ *
294
+ * const writer = new Writer({
295
+ * storage: new MemoryStorage(),
296
+ * currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
297
+ * });
298
+ *
299
+ * const result = await writer.commit({
300
+ * op: "I",
301
+ * collection: "tickets",
302
+ * docId: "doc-1",
303
+ * body: { _id: "doc-1", title: "hello" },
304
+ * });
305
+ * console.log(result.entry.seq, result.attempts);
306
+ * ```
307
+ */
308
+ var Writer = class {
309
+ #storage;
310
+ #currentJsonKey;
311
+ #maxRetries;
312
+ #initialBackoffMs;
313
+ #random;
314
+ #indexes;
315
+ #verifyLogIntegrityOnCommit;
316
+ constructor(opts) {
317
+ this.#storage = opts.storage;
318
+ this.#currentJsonKey = opts.currentJsonKey;
319
+ this.#maxRetries = opts.options?.maxRetries ?? 8;
320
+ this.#initialBackoffMs = opts.options?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
321
+ this.#random = opts.options?.random ?? Math.random;
322
+ const indexes = opts.options?.indexes ?? [];
323
+ for (const def of indexes) validateIndexDefinition(def);
324
+ this.#indexes = indexes;
325
+ this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
326
+ }
327
+ /**
328
+ * Atomically commit one mutation. Reads `current.json` fresh, mints
329
+ * the next log entry at `seq = current.next_seq`, PUTs the content
330
+ * body and the log entry, then CAS-advances `current.json` with
331
+ * `If-Match`. Retries on conflict up to `maxRetries`.
332
+ *
333
+ * The hot-path cost under no contention is 1 GET + 3 PUTs (4 ops);
334
+ * an in-flight peer write costs one extra GET + the backoff sleep
335
+ * per retry.
336
+ *
337
+ * Idempotency: PUT content uses `If-None-Match: "*"`, so a retry of
338
+ * the same logical write produces the same content key and the
339
+ * second PUT no-ops. PUT log entry also uses `If-None-Match: "*"`,
340
+ * so two writers racing the same `next_seq` cause exactly one PUT
341
+ * to land — the loser falls into the CAS retry path.
342
+ *
343
+ * @throws BaerlyError code="Conflict" when the retry budget is
344
+ * exhausted (genuine high-contention case), or when the underlying
345
+ * `current.json` CAS PUT lost.
346
+ * @throws BaerlyError code="Conflict" — the writer fence
347
+ * (`current.json.writer_fence.epoch`) was bumped by a concurrent
348
+ * `claimWriter` call between this commit's read of
349
+ * `current.json` and its CAS-advance. The stale writer aborts
350
+ * to honour the new authority — the kernel does NOT retry under
351
+ * the old epoch. See {@link claimWriter} for the rotation
352
+ * recipe.
353
+ * @throws BaerlyError code="Internal" when a log entry expected in
354
+ * `[0, next_seq)` is missing — a protocol-invariant violation
355
+ * (compactor bug or stale `current.json`).
356
+ * @throws BaerlyError code="InvalidResponse" when a log-entry body
357
+ * isn't valid JSON.
358
+ *
359
+ * **Implicit provisioning.** When `current.json` does not exist at
360
+ * `currentJsonKey` (fresh bucket, fresh collection), the writer
361
+ * auto-creates it with a zero-state manifest before the commit
362
+ * lands. The cost is one extra Class A PUT on the very first
363
+ * commit per collection; steady-state cost is unchanged. A peer
364
+ * racing the same first-write loses cleanly on the create CAS
365
+ * and re-reads to pick up the winner's manifest.
366
+ */
367
+ async commit(input) {
368
+ const session = uuid().slice(0, 6);
369
+ const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
370
+ for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {
371
+ let success;
372
+ try {
373
+ success = await this.#singleAttemptCommit([input], session, logPrefix, "Writer", true);
374
+ } catch (error) {
375
+ if (!isPreconditionFailed(error)) throw error;
376
+ await this.#backoff(attempt);
377
+ continue;
378
+ }
379
+ await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer");
380
+ this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));
381
+ return {
382
+ entry: success.entries[0],
383
+ currentEtag: success.currentEtag,
384
+ attempts: attempt
385
+ };
386
+ }
387
+ throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`);
388
+ }
389
+ /**
390
+ * Single-attempt batched commit. Reads `current.json` ONCE, mints
391
+ * `inputs.length` log entries with contiguous `seq` numbers
392
+ * starting at the current `next_seq`, PUTs each content body and
393
+ * each log entry, then CAS-advances `current.json` from
394
+ * `next_seq = N` to `next_seq = N + inputs.length` with
395
+ * `If-Match`.
396
+ *
397
+ * NO retry on CAS loss. On `current.json` 412, throws
398
+ * `BaerlyError{code:"Conflict"}` immediately — the caller (here:
399
+ * `Db.transaction`) decides whether to retry by re-running the
400
+ * body, or to surface to the app. Likewise on a log-entry 412
401
+ * (a peer wrote our seq).
402
+ *
403
+ * Empty `inputs`: returns `{ entries: [], currentEtag: undefined }`
404
+ * after zero storage operations.
405
+ *
406
+ * @throws BaerlyError code="Conflict" — CAS lost on `current.json`,
407
+ * or a log entry already exists at our seq (peer wrote ahead).
408
+ * @throws BaerlyError code="Conflict" — the writer fence
409
+ * (`current.json.writer_fence.epoch`) was bumped by a concurrent
410
+ * `claimWriter` call between this batch's read of
411
+ * `current.json` and its CAS-advance. The stale writer aborts
412
+ * to honour the new authority — the kernel does NOT retry under
413
+ * the old epoch. See {@link claimWriter} for the rotation
414
+ * recipe.
415
+ * @throws BaerlyError code="Internal" — protocol-invariant violation
416
+ * (missing log entry inside `[0, next_seq)`).
417
+ * @throws BaerlyError code="InvalidResponse" — malformed log body.
418
+ *
419
+ * **Implicit provisioning.** Like {@link commit}, this path auto-
420
+ * creates `current.json` with a zero-state manifest on a missing
421
+ * read. Because `commitBatch` does NOT retry on CAS loss, a peer
422
+ * racing the same first-write surfaces `Conflict` to the caller
423
+ * (`Db.transaction` re-runs the body); the manifest is durable
424
+ * regardless of which writer won the create.
425
+ */
426
+ async commitBatch(inputs) {
427
+ if (inputs.length === 0) return {
428
+ entries: [],
429
+ currentEtag: void 0
430
+ };
431
+ const session = uuid().slice(0, 6);
432
+ const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
433
+ const success = await this.#singleAttemptCommit(inputs, session, logPrefix, "Writer.commitBatch", false);
434
+ await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer.commitBatch");
435
+ this.#emitWriteMetrics(inputs[0].collection, success.classAOps);
436
+ return {
437
+ entries: success.entries,
438
+ currentEtag: success.currentEtag
439
+ };
440
+ }
441
+ /**
442
+ * One full commit attempt — the shared body of {@link commit} and
443
+ * {@link commitBatch}. Reads `current.json`, walks the log, mints N
444
+ * entries, PUTs content + indexes in parallel, PUTs log entries,
445
+ * CAS-advances `current.json`. Returns the success payload + the
446
+ * pre-commit fence epoch so the caller can run
447
+ * {@link #verifyFenceUnchanged} outside the retry-catch arm.
448
+ *
449
+ * Retryable failures (a peer wrote our seq; a peer won the CAS on
450
+ * `current.json`) throw `BaerlyError{code:"Conflict"}`. The caller
451
+ * catches via {@link isPreconditionFailed} and either retries
452
+ * (`commit`) or surfaces (`commitBatch`). Fence-bump and protocol-
453
+ * invariant violations are NOT thrown from this helper — the fence
454
+ * check lives in the caller so its `Conflict` propagates past the
455
+ * retry-catch arm. Other thrown `BaerlyError`s (Internal,
456
+ * InvalidResponse, NetworkError) bypass `isPreconditionFailed` and
457
+ * propagate naturally.
458
+ *
459
+ * Crash safety invariant: content / index PUTs are awaited before
460
+ * log PUTs, which are awaited before the CAS. A crashed mid-attempt
461
+ * writer leaves orphan content / index entries (no log entry
462
+ * references them) — the compactor sweeps the orphans. The
463
+ * inverse — orphan log entry with missing content — is never
464
+ * produced.
465
+ */
466
+ async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix, adoptOwnSessionOnLogConflict) {
467
+ const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
468
+ const current = read.json;
469
+ const baseEtag = read.etag;
470
+ const expectedEpoch = current.writer_fence.epoch;
471
+ if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.next_seq);
472
+ const entries = [];
473
+ for (let i = 0; i < inputs.length; i++) {
474
+ const input = inputs[i];
475
+ const seq = current.next_seq + i;
476
+ const entry = {
477
+ lsn: `${timestamp(Date.now())}_${session}_${countKey(seq)}`,
478
+ commit_ts: (/* @__PURE__ */ new Date()).toISOString(),
479
+ op: input.op,
480
+ collection: input.collection,
481
+ doc_id: input.docId,
482
+ schema_version: 0,
483
+ session,
484
+ seq,
485
+ ...input.op !== "D" && input.body !== void 0 ? {
486
+ new: input.body,
487
+ patch: input.body
488
+ } : {},
489
+ ...input.origin !== void 0 ? { origin: input.origin } : {}
490
+ };
491
+ entries.push(entry);
492
+ }
493
+ let contentPutCount = 0;
494
+ let indexClassA = 0;
495
+ const parallelPuts = [];
496
+ const inBatchImage = /* @__PURE__ */ new Map();
497
+ for (const input of inputs) {
498
+ if (input.op !== "D" && input.body !== void 0) {
499
+ contentPutCount++;
500
+ const bytes = encodeJsonBytes(input.body);
501
+ const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
502
+ parallelPuts.push(this.#storage.put(contentKey, bytes, {
503
+ ifNoneMatch: "*",
504
+ contentType: APPLICATION_JSON
505
+ }).catch((error) => {
506
+ this.#observe429(error, input.collection);
507
+ if (isPreconditionFailed(error)) return;
508
+ throw error;
509
+ }));
510
+ }
511
+ if (this.#indexes.length > 0) {
512
+ let newKeys = [];
513
+ let staleKeys = [];
514
+ if (input.op === "I") newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
515
+ else if (input.op === "U") {
516
+ const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
517
+ const oldKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
518
+ newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
519
+ const newSet = new Set(newKeys);
520
+ staleKeys = oldKeys.filter((k) => !newSet.has(k));
521
+ } else {
522
+ const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
523
+ staleKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
524
+ }
525
+ for (const k of newKeys) parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
526
+ ifNoneMatch: "*",
527
+ contentType: APPLICATION_JSON
528
+ }).catch((error) => {
529
+ this.#observe429(error, input.collection);
530
+ if (isPreconditionFailed(error)) return;
531
+ throw error;
532
+ }));
533
+ for (const k of staleKeys) parallelPuts.push(this.#storage.delete(k));
534
+ indexClassA += newKeys.length + staleKeys.length;
535
+ if (newKeys.length + staleKeys.length > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", newKeys.length + staleKeys.length, { collection: input.collection });
536
+ inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
537
+ }
538
+ }
539
+ await Promise.all(parallelPuts);
540
+ const logPutOne = async (entry) => {
541
+ const logEntryKey = `${logPrefix}/log/${entry.seq}.json`;
542
+ const logBytes = encodeJsonBytes(entry);
543
+ try {
544
+ await this.#storage.put(logEntryKey, logBytes, {
545
+ ifNoneMatch: "*",
546
+ contentType: APPLICATION_JSON
547
+ });
548
+ return { ok: true };
549
+ } catch (error) {
550
+ this.#observe429(error, entry.collection);
551
+ if (!isPreconditionFailed(error)) throw error;
552
+ ctxMetrics().counter("db.r2.put.412_total", 1, {
553
+ collection: entry.collection,
554
+ step: "log-put"
555
+ });
556
+ return { ok: false };
557
+ }
558
+ };
559
+ const logPutResults = await Promise.all(entries.map(logPutOne));
560
+ let committedEntries = entries;
561
+ const firstConflictIdx = logPutResults.findIndex((r) => !r.ok);
562
+ if (firstConflictIdx !== -1) {
563
+ const conflictedEntry = entries[firstConflictIdx];
564
+ const logEntryKey = `${logPrefix}/log/${conflictedEntry.seq}.json`;
565
+ if (adoptOwnSessionOnLogConflict) {
566
+ const decision = tryAdoptOwnSessionLogEntry({
567
+ self: conflictedEntry,
568
+ existing: await readLogEntry(this.#storage, logEntryKey),
569
+ batchSize: inputs.length
570
+ });
571
+ if (decision.adopt) committedEntries = [decision.entry];
572
+ else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; ${decision.reason}`);
573
+ } else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; peer wrote our seq`);
574
+ }
575
+ const nextBody = encodeJsonBytes({
576
+ ...current,
577
+ next_seq: current.next_seq + inputs.length
578
+ });
579
+ const putOpts = {
580
+ ifMatch: baseEtag,
581
+ contentType: APPLICATION_JSON
582
+ };
583
+ let result;
584
+ try {
585
+ result = await this.#storage.put(this.#currentJsonKey, nextBody, putOpts);
586
+ } catch (error) {
587
+ this.#observe429(error, inputs[0].collection);
588
+ if (isPreconditionFailed(error)) {
589
+ ctxMetrics().counter("db.r2.put.412_total", 1, {
590
+ collection: inputs[0].collection,
591
+ step: "current-json-cas"
592
+ });
593
+ throw new BaerlyError("Conflict", `${errorPrefix}: CAS conflict on ${this.#currentJsonKey}`);
594
+ }
595
+ throw error;
596
+ }
597
+ const classAOps = contentPutCount + entries.length + indexClassA + 1;
598
+ return {
599
+ entries: committedEntries,
600
+ currentEtag: result.etag,
601
+ classAOps,
602
+ expectedEpoch
603
+ };
604
+ }
605
+ /**
606
+ * Read the pre-image content body for a doc by walking the live
607
+ * log backwards from `currentNextSeq` looking for the
608
+ * most-recent I/U entry on this `(collection, docId)`. Returns
609
+ * `undefined` when:
610
+ *
611
+ * - the doc's most-recent op was `D` (tombstone — no live body);
612
+ * - no entry for this doc lives inside the visible log range
613
+ * `[log_seq_start, currentNextSeq)` (a fresh-insert race or
614
+ * the doc has been folded into the snapshot but is no longer
615
+ * referenced).
616
+ *
617
+ * Used ONLY by the index-emission path on `U` / `D` to compute
618
+ * the stale-key set. Bounded by `log_seq_start`: entries below
619
+ * have been folded into the snapshot and may already be swept
620
+ * off the bucket — a snapshot fold is the rebuild command's job
621
+ * (see `./rebuild-index.ts`), not the writer's.
622
+ *
623
+ * **Cost note:** linear walk, O(snapshot lag). For day-one Phase
624
+ * 8 collections (helpdesk-shape: 100s of docs, <10k log entries)
625
+ * this is fine — the compactor folds the live tail every ~100
626
+ * entries (`packages/server/src/compactor.ts`). A follow-up ticket
627
+ * caches per-doc index head in `current.json` for O(1) lookup.
628
+ * The bound is documented; out of scope here.
629
+ */
630
+ /**
631
+ * Auto-create the per-collection `current.json` at
632
+ * `this.#currentJsonKey` with a zero-state initial manifest. Called
633
+ * by `#singleAttemptCommit` when the read returned `null` (fresh
634
+ * bucket / fresh collection).
635
+ *
636
+ * Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
637
+ * peer raced us and won, the storage layer surfaces `Conflict`; we
638
+ * recover by re-reading the now-present manifest. We do NOT retry
639
+ * the create — a single recover-via-read covers every race that
640
+ * could have produced our null read.
641
+ *
642
+ * The seed shape (`snapshot: null`, `next_seq: 0`, `log_seq_start:
643
+ * 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
644
+ * matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
645
+ * operator who pre-provisions and a writer who auto-creates land
646
+ * on byte-identical bytes.
647
+ *
648
+ * @throws BaerlyError code="InvalidResponse" — the post-recover
649
+ * re-read also returned null. Defensive guard; in practice
650
+ * unreachable because the Conflict implies the key now exists.
651
+ */
652
+ async #provisionCurrentJson() {
653
+ const initial = {
654
+ schema_version: 1,
655
+ snapshot: null,
656
+ next_seq: 0,
657
+ log_seq_start: 0,
658
+ writer_fence: {
659
+ epoch: 0,
660
+ owner: "",
661
+ claimed_at: ""
662
+ }
663
+ };
664
+ try {
665
+ return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
666
+ } catch (error) {
667
+ if (!(error instanceof BaerlyError) || error.code !== "Conflict") throw error;
668
+ }
669
+ const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
670
+ if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
671
+ return recovered;
672
+ }
673
+ async #readPreImage(logPrefix, collection, docId, currentNextSeq) {
674
+ for (let s = currentNextSeq - 1; s >= 0; s--) {
675
+ const logKey = `${logPrefix}/log/${s}.json`;
676
+ const got = await this.#storage.get(logKey);
677
+ if (got === null) continue;
678
+ let entry;
679
+ try {
680
+ entry = decodeJsonBytes(got.body);
681
+ } catch {
682
+ continue;
683
+ }
684
+ if (entry.collection !== collection || entry.doc_id !== docId) continue;
685
+ if (entry.op === "D") return;
686
+ if ((entry.op === "I" || entry.op === "U") && entry.new !== void 0) return entry.new;
687
+ }
688
+ }
689
+ /**
690
+ * Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with
691
+ * bounded parallelism via `walkLogRange`. Materialised entries are
692
+ * discarded — the walk's only job is to surface a hole or a
693
+ * malformed body inside the visible range as
694
+ * `BaerlyError{code:"Internal"}` / `"InvalidResponse"`.
695
+ *
696
+ * Gated on `verifyLogIntegrityOnCommit`; default off in production
697
+ * because the per-doc fold already lives in the read path. See the
698
+ * option's docstring for the rationale and the opt-in convention.
699
+ *
700
+ * `logSeqStart` is the boundary set by the compactor on
701
+ * `current.json.log_seq_start`. Entries below it have been folded
702
+ * into the snapshot and may have been swept off the bucket, so the
703
+ * walk MUST NOT GET-require them.
704
+ */
705
+ async #walkLog(logPrefix, logSeqStart, nextSeq) {
706
+ await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);
707
+ }
708
+ /**
709
+ * Bump the `db.r2.put.429_total` counter when `err` looks like an
710
+ * R2 prefix-partition rate-limit. Best-effort: detected via
711
+ * `BaerlyError{code:"NetworkError"}` with a `429` token in the
712
+ * message. Called from every PUT call site's catch arm; mutually
713
+ * exclusive in practice with `isPreconditionFailed` (412 ≠ 429).
714
+ */
715
+ #observe429(err, collection) {
716
+ if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
717
+ }
718
+ /**
719
+ * Emit the per-logical-write `class_a_ops_per_logical_write`
720
+ * histogram shared by `commit` and `commitBatch`. `classAOps`
721
+ * differs between the two paths (retry-budget vs batch shape),
722
+ * so each caller computes it.
723
+ */
724
+ #emitWriteMetrics(collection, classAOps) {
725
+ ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
726
+ }
727
+ /**
728
+ * Re-read `current.json` after a successful CAS and assert the
729
+ * writer-fence epoch is still ours. The CAS only mutated `next_seq`
730
+ * (the fence is preserved from `current`), so a post-write epoch
731
+ * mismatch can only mean another writer claimed the fence between
732
+ * our step-1 read and step-6 PUT — the exact split-brain
733
+ * `WriterFence` prevents. Throws `Conflict`; no retry, since the
734
+ * stale writer must defer to the new authority.
735
+ *
736
+ * The fence-verify GET is Class B and intentionally NOT counted in
737
+ * `class_a_ops_per_logical_write`.
738
+ */
739
+ async #verifyFenceUnchanged(expectedEpoch, where) {
740
+ const postRead = await readCurrentJson(this.#storage, this.#currentJsonKey);
741
+ if (postRead === null) return;
742
+ if (postRead.json.writer_fence.epoch === expectedEpoch) return;
743
+ throw new BaerlyError("Conflict", `${where}: writer fence bumped from epoch ${expectedEpoch} to ${postRead.json.writer_fence.epoch} during commit on ${this.#currentJsonKey}; stale writer aborting`);
744
+ }
745
+ /**
746
+ * Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
747
+ * at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
748
+ * from re-racing in lockstep. Worst-case total wait across the
749
+ * default 8 attempts is roughly 2.5 s — well under a typical
750
+ * Worker request budget.
751
+ */
752
+ async #backoff(attempt) {
753
+ const sleepMs = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS) * this.#random();
754
+ if (sleepMs <= 0) return;
755
+ await new Promise((r) => setTimeout(r, sleepMs));
756
+ }
757
+ };
758
+ /**
759
+ * `true` when the underlying storage surfaced a `PreconditionFailed`
760
+ * 412 (or its non-S3 equivalents). Every in-tree {@link Storage} impl
761
+ * surfaces a lost CAS as `BaerlyError{code:"Conflict"}`.
762
+ */
763
+ const isPreconditionFailed = (err) => err instanceof BaerlyError && err.code === "Conflict";
764
+ /**
765
+ * `true` when the underlying storage surfaced an R2 prefix-partition
766
+ * rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
767
+ * onto `BaerlyError.cause` as `{ status }`; we discriminate on that
768
+ * structured field rather than regex-matching the message.
769
+ */
770
+ const is429 = (err) => {
771
+ if (!(err instanceof BaerlyError) || err.code !== "NetworkError") return false;
772
+ return err.cause?.status === 429;
773
+ };
774
+ //#endregion
775
+ //#region packages/server/src/query-planner-implies.ts
776
+ /**
777
+ * Filtered-index implication checker — decides whether every
778
+ * document accepted by a query predicate is also accepted by a
779
+ * filtered index's predicate. The query planner uses the result to
780
+ * rank candidate indexes; see {@link "./query-planner.ts".planQuery}.
781
+ *
782
+ * Pure-function module: no I/O, no `Db` / `Storage` imports. Lives
783
+ * in `@baerly/server` (not in `@baerly/protocol`) because the
784
+ * planner is the only caller.
785
+ *
786
+ * Operates on the wire form: both inputs are {@link PredicateWire}s
787
+ * with clauses already grouped by `(op, field, value)`. The
788
+ * normaliser at `@baerly/protocol`'s `./query/normalize.ts` has
789
+ * already flattened nested literal sub-predicates into dotted-path
790
+ * `eq` clauses, so there is no recursion on nested objects here.
791
+ */
792
+ /**
793
+ * Group a wire's clauses by `field` so the per-field implication
794
+ * check can reason over one bundle at a time. Inlined small helper
795
+ * (not exported) so the planner module doesn't need to expose its
796
+ * grouping helper as a cross-module contract.
797
+ */
798
+ const groupByField = (wire) => {
799
+ const groups = /* @__PURE__ */ new Map();
800
+ for (const clause of wire.clauses) {
801
+ const bucket = groups.get(clause.field);
802
+ if (bucket === void 0) groups.set(clause.field, [clause]);
803
+ else bucket.push(clause);
804
+ }
805
+ return groups;
806
+ };
807
+ /**
808
+ * Collapse a per-field clause list into an {@link OperatorBundle}.
809
+ * Returns `"unknown-shape"` when the group has more than one `in`
810
+ * clause (set-intersection at plan time is out of scope) or
811
+ * unrecognised ops slipping through (defensive — the validator
812
+ * already locked the op vocabulary). Multiple `eq` clauses on one
813
+ * field: the validator proves they all agree, so we pick the first.
814
+ * Multiple range clauses on one field: take the strictest bound
815
+ * (tightest `lo` = numerically largest; tightest `hi` = numerically
816
+ * smallest).
817
+ */
818
+ const decodeGroup = (clauses) => {
819
+ const bundle = {};
820
+ for (const clause of clauses) {
821
+ const v = clause.value;
822
+ if (clause.op === "eq") bundle.eq = v;
823
+ else if (clause.op === "gte") {
824
+ const next = {
825
+ value: v,
826
+ inclusive: true
827
+ };
828
+ bundle.lo = tightestLo(bundle.lo, next);
829
+ } else if (clause.op === "gt") {
830
+ const next = {
831
+ value: v,
832
+ inclusive: false
833
+ };
834
+ bundle.lo = tightestLo(bundle.lo, next);
835
+ } else if (clause.op === "lte") {
836
+ const next = {
837
+ value: v,
838
+ inclusive: true
839
+ };
840
+ bundle.hi = tightestHi(bundle.hi, next);
841
+ } else if (clause.op === "lt") {
842
+ const next = {
843
+ value: v,
844
+ inclusive: false
845
+ };
846
+ bundle.hi = tightestHi(bundle.hi, next);
847
+ } else if (clause.op === "in") {
848
+ if (bundle.in !== void 0) return "unknown-shape";
849
+ if (!Array.isArray(v)) return "unknown-shape";
850
+ bundle.in = v;
851
+ } else return "unknown-shape";
852
+ }
853
+ return bundle;
854
+ };
855
+ const tightestLo = (existing, next) => {
856
+ if (existing === void 0) return next;
857
+ if (typeof existing.value !== typeof next.value) return existing;
858
+ if (next.value > existing.value) return next;
859
+ if (next.value < existing.value) return existing;
860
+ if (!next.inclusive && existing.inclusive) return next;
861
+ return existing;
862
+ };
863
+ const tightestHi = (existing, next) => {
864
+ if (existing === void 0) return next;
865
+ if (typeof existing.value !== typeof next.value) return existing;
866
+ if (next.value < existing.value) return next;
867
+ if (next.value > existing.value) return existing;
868
+ if (!next.inclusive && existing.inclusive) return next;
869
+ return existing;
870
+ };
871
+ /**
872
+ * Does the query's lower bound `loQ` (`undefined` if none) prove that
873
+ * every matching doc satisfies the filter's lower bound `loF`?
874
+ *
875
+ * `loF.inclusive` true → need doc ≥ loF.value; `loF.inclusive` false →
876
+ * need doc > loF.value. A stricter `loQ` (numerically larger or with
877
+ * tighter inclusivity) always implies a looser `loF`.
878
+ */
879
+ const lowerBoundImplies = (loF, loQ) => {
880
+ if (loQ === void 0) return false;
881
+ if (typeof loF.value !== typeof loQ.value) return false;
882
+ if (loQ.value > loF.value) return true;
883
+ if (loQ.value < loF.value) return false;
884
+ if (loF.inclusive) return true;
885
+ return !loQ.inclusive;
886
+ };
887
+ /** Mirror of lowerBoundImplies for upper bounds. */
888
+ const upperBoundImplies = (hiF, hiQ) => {
889
+ if (hiQ === void 0) return false;
890
+ if (typeof hiF.value !== typeof hiQ.value) return false;
891
+ if (hiQ.value < hiF.value) return true;
892
+ if (hiQ.value > hiF.value) return false;
893
+ if (hiF.inclusive) return true;
894
+ return !hiQ.inclusive;
895
+ };
896
+ const loFromQuery = (q) => {
897
+ if (q.eq !== void 0) return {
898
+ value: q.eq,
899
+ inclusive: true
900
+ };
901
+ if (q.in !== void 0 && q.in.length > 0) return {
902
+ value: q.in.reduce((acc, v) => v < acc ? v : acc, q.in[0]),
903
+ inclusive: true
904
+ };
905
+ return q.lo;
906
+ };
907
+ const hiFromQuery = (q) => {
908
+ if (q.eq !== void 0) return {
909
+ value: q.eq,
910
+ inclusive: true
911
+ };
912
+ if (q.in !== void 0 && q.in.length > 0) return {
913
+ value: q.in.reduce((acc, v) => v > acc ? v : acc, q.in[0]),
914
+ inclusive: true
915
+ };
916
+ return q.hi;
917
+ };
918
+ /**
919
+ * Filtered-index implication checker — decides whether every document
920
+ * accepted by `queryWire` is also accepted by `indexFilterWire`. When
921
+ * `true`, a walk over an index declared with `predicate: indexFilterWire`
922
+ * is **complete** for `queryWire`: no matching doc is missing
923
+ * from the smaller key set, so the planner can prefer it.
924
+ *
925
+ * Implication on `eq`, `gt` / `gte`, `lt` / `lte`, and `in` is
926
+ * sound and complete in pure operator form; combined shapes (e.g.
927
+ * range-on-filter and `in`-on-query) follow the algebra in the body
928
+ * JSDoc.
929
+ *
930
+ * Algorithm — group both wires by `field`, then for every field
931
+ * present in `indexFilterWire`:
932
+ *
933
+ * 1. Decode the filter's clause group into an {@link OperatorBundle}.
934
+ * "unknown-shape" → refuse implication conservatively.
935
+ * 2. The query MUST have at least one clause on that field —
936
+ * otherwise the query says nothing about that field and cannot
937
+ * possibly imply the filter's constraint.
938
+ * 3. Decode the query's clause group on the same field.
939
+ * 4. For each non-empty slot of the filter bundle, the query bundle
940
+ * must establish the constraint:
941
+ * - `eq` → query establishes equality (via its own `eq`).
942
+ * - `in` → query is contained in the set (via `eq` ∈ set or
943
+ * `in` ⊆ set).
944
+ * - `lo` / `hi` → query establishes the bound via `eq`, `in`
945
+ * (then min/max of the set), or its own `lo`/`hi` with the
946
+ * inclusivity rules in {@link lowerBoundImplies} /
947
+ * {@link upperBoundImplies}.
948
+ * Mixed types (e.g. number filter vs string query) refuse
949
+ * implication conservatively.
950
+ *
951
+ * Returns `true` iff every clause was satisfied. An empty
952
+ * `indexFilterWire` is vacuously implied by any `queryWire`.
953
+ *
954
+ * Soundness contract — when this function returns `true`,
955
+ * `matchesWire(queryWire, doc) ⇒ matchesWire(indexFilterWire, doc)` for
956
+ * any document `doc`. Tests pin this property; see
957
+ * `./query-planner-implies.test.ts`.
958
+ */
959
+ const predicateImplies = (indexFilterWire, queryWire) => {
960
+ const filterGroups = groupByField(indexFilterWire);
961
+ const queryGroups = groupByField(queryWire);
962
+ for (const [field, filterClauses] of filterGroups) {
963
+ const filterBundle = decodeGroup(filterClauses);
964
+ if (filterBundle === "unknown-shape") return false;
965
+ const queryClauses = queryGroups.get(field);
966
+ if (queryClauses === void 0) return false;
967
+ const queryBundle = decodeGroup(queryClauses);
968
+ if (queryBundle === "unknown-shape") return false;
969
+ if (filterBundle.eq !== void 0) {
970
+ if (queryBundle.eq === void 0) return false;
971
+ if (!deepEqualDocumentValue(queryBundle.eq, filterBundle.eq)) return false;
972
+ continue;
973
+ }
974
+ if (filterBundle.in !== void 0) {
975
+ const set = filterBundle.in;
976
+ const contains = (v) => set.some((m) => deepEqualDocumentValue(m, v));
977
+ if (queryBundle.eq !== void 0) {
978
+ if (!contains(queryBundle.eq)) return false;
979
+ } else if (queryBundle.in !== void 0) {
980
+ for (const v of queryBundle.in) if (!contains(v)) return false;
981
+ } else return false;
982
+ continue;
983
+ }
984
+ if (filterBundle.lo !== void 0) {
985
+ if (!lowerBoundImplies(filterBundle.lo, loFromQuery(queryBundle))) return false;
986
+ }
987
+ if (filterBundle.hi !== void 0) {
988
+ if (!upperBoundImplies(filterBundle.hi, hiFromQuery(queryBundle))) return false;
989
+ }
990
+ }
991
+ return true;
992
+ };
993
+ /**
994
+ * Choose a query plan over the wire predicate + declared indexes.
995
+ * Pure function. The executor enforces the I/O semantics; the
996
+ * planner's only contract is "given these inputs, this is the
997
+ * routing decision."
998
+ *
999
+ * Algorithm:
1000
+ * 1. `wire === undefined` or empty → `no-predicate`.
1001
+ * 2. `indexes.length === 0` → `no-indexes-declared`.
1002
+ * 3. Partition wire clauses per field into:
1003
+ * - `equality[f] = v` from `eq` clauses.
1004
+ * - `rangeOps[f] = {lo, hi, loInclusive, hiInclusive}` from
1005
+ * one or more of `gt`/`gte`/`lt`/`lte` clauses on `f`.
1006
+ * - `inOps[f] = [...]` from a single `in` clause on `f`.
1007
+ * - Defensive: any field whose clause group mixes op-channels
1008
+ * (mostly impossible post-validation) is marked unroutable
1009
+ * and skipped — the executor's full-wire `matchesWire(...)`
1010
+ * post-fetch catches the residue automatically.
1011
+ * 4. If no equality / range / `in` candidates exist →
1012
+ * `predicate-uses-operators-only`.
1013
+ * 5. For each `def`, walk `def.on` left-to-right consuming
1014
+ * equality clauses for each indexed field. On the FIRST field
1015
+ * where the equality clause is absent, check whether a range
1016
+ * or `in` clause is available for that field — if so, that's
1017
+ * the "tail slot" of the walk.
1018
+ * 6. Score candidates by `(equalityPrefixLen, hasTailExtension)`.
1019
+ * Longest prefix wins; tail-extension breaks ties. If no
1020
+ * candidate consumed at least one field (equality OR
1021
+ * range/`in`): `no-matching-index`.
1022
+ * 7. `in` FAN-OUT GUARD: if the chosen plan's `in` slot has
1023
+ * `values.length > IN_FANOUT_THRESHOLD`, fall back to
1024
+ * `FullScanPlan{reason:"no-matching-index"}` — N sequential
1025
+ * LISTs cost more than a snapshot+log fold.
1026
+ *
1027
+ * The planner deliberately treats `def.on` as the LITERAL tuple of
1028
+ * field names — top-level only. Dotted paths are out of scope here
1029
+ * (the projector at `indexes.ts:projectIndexValues` is top-level-
1030
+ * only too).
1031
+ *
1032
+ * **Range/`in` is allowed only on the LAST indexed field beyond the
1033
+ * equality prefix** — on a composite `[a, b]`, a range on `a` with
1034
+ * equality on `b` is NOT contiguous under the key encoding (the `b`
1035
+ * slot sits to the right of the varying `a` slot). Clauses landing
1036
+ * outside the tail slot are simply left for the executor's full-
1037
+ * predicate re-check.
1038
+ */
1039
+ const planQuery = (wire, indexes) => {
1040
+ if (wire === void 0 || wire.clauses.length === 0) return {
1041
+ kind: "full-scan",
1042
+ reason: "no-predicate"
1043
+ };
1044
+ if (indexes.length === 0) return {
1045
+ kind: "full-scan",
1046
+ reason: "no-indexes-declared"
1047
+ };
1048
+ const equality = /* @__PURE__ */ new Map();
1049
+ const rangeOps = /* @__PURE__ */ new Map();
1050
+ const inOps = /* @__PURE__ */ new Map();
1051
+ const unroutable = /* @__PURE__ */ new Set();
1052
+ const rangeAcc = /* @__PURE__ */ new Map();
1053
+ for (const clause of wire.clauses) {
1054
+ const field = clause.field;
1055
+ if (unroutable.has(field)) continue;
1056
+ if (clause.op === "eq") {
1057
+ if (inOps.has(field) || rangeAcc.has(field)) {
1058
+ unroutable.add(field);
1059
+ equality.delete(field);
1060
+ inOps.delete(field);
1061
+ rangeAcc.delete(field);
1062
+ continue;
1063
+ }
1064
+ equality.set(field, clause.value);
1065
+ } else if (clause.op === "in") {
1066
+ if (equality.has(field) || rangeAcc.has(field) || inOps.has(field)) {
1067
+ unroutable.add(field);
1068
+ equality.delete(field);
1069
+ inOps.delete(field);
1070
+ rangeAcc.delete(field);
1071
+ continue;
1072
+ }
1073
+ if (!Array.isArray(clause.value)) {
1074
+ unroutable.add(field);
1075
+ continue;
1076
+ }
1077
+ inOps.set(field, clause.value);
1078
+ } else {
1079
+ if (equality.has(field) || inOps.has(field)) {
1080
+ unroutable.add(field);
1081
+ equality.delete(field);
1082
+ inOps.delete(field);
1083
+ rangeAcc.delete(field);
1084
+ continue;
1085
+ }
1086
+ const acc = rangeAcc.get(field) ?? {
1087
+ loInclusive: false,
1088
+ hiInclusive: false
1089
+ };
1090
+ const v = clause.value;
1091
+ if (clause.op === "gte") {
1092
+ if (acc.lo === void 0 || v > acc.lo) {
1093
+ acc.lo = v;
1094
+ acc.loInclusive = true;
1095
+ } else if (v === acc.lo && !acc.loInclusive) {}
1096
+ } else if (clause.op === "gt") {
1097
+ if (acc.lo === void 0 || v > acc.lo) {
1098
+ acc.lo = v;
1099
+ acc.loInclusive = false;
1100
+ } else if (v === acc.lo) acc.loInclusive = false;
1101
+ } else if (clause.op === "lte") {
1102
+ if (acc.hi === void 0 || v < acc.hi) {
1103
+ acc.hi = v;
1104
+ acc.hiInclusive = true;
1105
+ }
1106
+ } else if (clause.op === "lt") {
1107
+ if (acc.hi === void 0 || v < acc.hi) {
1108
+ acc.hi = v;
1109
+ acc.hiInclusive = false;
1110
+ } else if (v === acc.hi) acc.hiInclusive = false;
1111
+ }
1112
+ rangeAcc.set(field, acc);
1113
+ }
1114
+ }
1115
+ for (const [field, acc] of rangeAcc) rangeOps.set(field, {
1116
+ ...acc.lo !== void 0 ? { lo: acc.lo } : {},
1117
+ ...acc.hi !== void 0 ? { hi: acc.hi } : {},
1118
+ loInclusive: acc.loInclusive,
1119
+ hiInclusive: acc.hiInclusive
1120
+ });
1121
+ if (equality.size === 0 && rangeOps.size === 0 && inOps.size === 0) return {
1122
+ kind: "full-scan",
1123
+ reason: "predicate-uses-operators-only"
1124
+ };
1125
+ const candidates = [];
1126
+ for (let defIndex = 0; defIndex < indexes.length; defIndex++) {
1127
+ const def = indexes[defIndex];
1128
+ const tuple = typeof def.on === "string" ? [def.on] : def.on;
1129
+ const equalityKeys = [];
1130
+ let tail;
1131
+ for (let i = 0; i < tuple.length; i++) {
1132
+ const field = tuple[i];
1133
+ const v = equality.get(field);
1134
+ if (v !== void 0) {
1135
+ equalityKeys.push(v);
1136
+ continue;
1137
+ }
1138
+ const range = rangeOps.get(field);
1139
+ if (range !== void 0) tail = {
1140
+ kind: "range",
1141
+ field,
1142
+ info: range
1143
+ };
1144
+ else {
1145
+ const inVals = inOps.get(field);
1146
+ if (inVals !== void 0) tail = {
1147
+ kind: "in",
1148
+ field,
1149
+ values: inVals
1150
+ };
1151
+ }
1152
+ break;
1153
+ }
1154
+ const candidateLen = equalityKeys.length + (tail !== void 0 ? 1 : 0);
1155
+ if (candidateLen === 0) continue;
1156
+ candidates.push({
1157
+ def,
1158
+ defIndex,
1159
+ prefixLen: candidateLen,
1160
+ equalityKeys,
1161
+ ...tail !== void 0 ? { tail } : {}
1162
+ });
1163
+ }
1164
+ if (candidates.length === 0) return {
1165
+ kind: "full-scan",
1166
+ reason: "no-matching-index"
1167
+ };
1168
+ const rank = (c) => {
1169
+ if (c.def.predicate === void 0) return 1;
1170
+ return predicateImplies(c.def.predicate, wire) ? 0 : 2;
1171
+ };
1172
+ candidates.sort((a, b) => {
1173
+ const aRank = rank(a);
1174
+ const bRank = rank(b);
1175
+ if (aRank !== bRank) return aRank - bRank;
1176
+ if (b.prefixLen !== a.prefixLen) return b.prefixLen - a.prefixLen;
1177
+ return a.defIndex - b.defIndex;
1178
+ });
1179
+ const best = candidates[0];
1180
+ if (best.tail !== void 0 && best.tail.kind === "in") {
1181
+ if (best.tail.values.length > 50) return {
1182
+ kind: "full-scan",
1183
+ reason: "no-matching-index"
1184
+ };
1185
+ }
1186
+ return {
1187
+ kind: "index-walk",
1188
+ indexName: best.def.name,
1189
+ equalityKeys: best.equalityKeys,
1190
+ ...best.tail !== void 0 && best.tail.kind === "range" ? { rangeOn: {
1191
+ field: best.tail.field,
1192
+ ...best.tail.info.lo !== void 0 ? { lo: best.tail.info.lo } : {},
1193
+ ...best.tail.info.hi !== void 0 ? { hi: best.tail.info.hi } : {},
1194
+ loInclusive: best.tail.info.loInclusive,
1195
+ hiInclusive: best.tail.info.hiInclusive
1196
+ } } : {},
1197
+ ...best.tail !== void 0 && best.tail.kind === "in" ? { inOn: {
1198
+ field: best.tail.field,
1199
+ values: best.tail.values
1200
+ } } : {}
1201
+ };
1202
+ };
1203
+ //#endregion
1204
+ //#region packages/server/src/schema.ts
1205
+ /**
1206
+ * Schema-validator runtime helper for `Db.insert` / `Query.update` /
1207
+ * `Collection.replace` boundary checks.
1208
+ *
1209
+ * The `SchemaValidator` / `SchemaIssue` TYPES live in
1210
+ * `@baerly/protocol` (cross-platform). This module owns the runtime
1211
+ * helper `validateOrThrow` that runs a validator and raises a
1212
+ * `BaerlyError{code:"SchemaError"}` on failure.
1213
+ *
1214
+ * @example
1215
+ * ```ts
1216
+ * import { z } from "zod";
1217
+ * import { defineConfig } from "@gusto/baerly-storage/config";
1218
+ *
1219
+ * const Ticket = z.object({
1220
+ * _id: z.string(),
1221
+ * status: z.enum(["open", "closed"]),
1222
+ * title: z.string().min(1),
1223
+ * });
1224
+ *
1225
+ * export default defineConfig({
1226
+ * collections: {
1227
+ * tickets: { schema: Ticket },
1228
+ * },
1229
+ * });
1230
+ * ```
1231
+ */
1232
+ /**
1233
+ * Run a validator and throw `BaerlyError{code:"SchemaError"}` on failure.
1234
+ * On success returns the validator's output (which for transforming
1235
+ * validators may differ from the input).
1236
+ *
1237
+ * Field paths are normalised to `(string | number)[]` so the wire shape
1238
+ * is JSON-clean. Symbol keys (rare; StandardSchemaV1 permits them) are
1239
+ * coerced to `String(sym)` — we never emit `symbol` on the wire.
1240
+ *
1241
+ * The thrown error's `message` carries a one-line summary
1242
+ * (`"<collection>.<verb>: <issuesCount> field(s) failed validation: <first>"`)
1243
+ * for stderr-readable logs; the structured `issues` are on `.issues`.
1244
+ */
1245
+ const validateOrThrow = async (schema, candidate, context) => {
1246
+ const result = await schema["~standard"].validate(candidate);
1247
+ if (result.issues === void 0) return result.value;
1248
+ const issues = result.issues.map((i) => ({
1249
+ path: (i.path ?? []).map((p) => {
1250
+ const raw = typeof p === "object" && p !== null && "key" in p ? p.key : p;
1251
+ return typeof raw === "number" ? raw : String(raw);
1252
+ }),
1253
+ message: i.message
1254
+ }));
1255
+ const first = issues[0];
1256
+ const summary = first === void 0 ? "schema validation failed (no issues reported)" : `${first.path.length === 0 ? "<root>" : first.path.join(".")}: ${first.message}`;
1257
+ throw new BaerlyError("SchemaError", `${context.collection}.${context.verb}: ${issues.length} field${issues.length === 1 ? "" : "s"} failed validation: ${summary}`, void 0, issues);
1258
+ };
1259
+ //#endregion
1260
+ //#region packages/server/src/query.ts
1261
+ /**
1262
+ * Read engine + mutation terminals: `Query<T>` builder, the
1263
+ * three read terminals (`first`, `all`, `count`) that fold the log
1264
+ * under a fresh `current.json` snapshot, and the four mutation
1265
+ * terminals (`insert`, `update`, `replace`, `delete`) that each
1266
+ * compile to one or more `Writer.commit()` round-trips.
1267
+ *
1268
+ * Every modifier (`.where` / `.order` / `.limit`) returns a NEW
1269
+ * `Query<T>` carrying merged frozen state — the input state is never
1270
+ * mutated. Identity inequality between the original and the returned
1271
+ * builder is intentional: callers cannot share a chain.
1272
+ *
1273
+ * `.where()` AND-merges through `mergePredicateWires` (clause-level
1274
+ * AND on the normalised wire form).
1275
+ * `.order()` and `.limit()` are last-call-wins (state replace).
1276
+ *
1277
+ * Each terminal reads `current.json` FRESH and walks `[0, next_seq)`
1278
+ * directly — no cache, no `list()` round-trip. Per the multi-
1279
+ * instance rules, every read sees a fresh CAS snapshot.
1280
+ *
1281
+ * Mutation terminals are SINGLE-ATTEMPT per call site. CAS contention
1282
+ * retries (up to 8 attempts) live inside `Writer.commit()`; the
1283
+ * verbs do NOT add their own retry loop. On retry-budget exhaustion
1284
+ * `commit()` throws `BaerlyError{code:"Conflict"}` and the verb
1285
+ * surfaces it unchanged — the caller's option is to wrap in
1286
+ * `db.transaction(...)`.
1287
+ *
1288
+ * @see ../../../docs/spec/sync-protocol.md
1289
+ */
1290
+ /**
1291
+ * Serialise a {@link CurrentJson} head into the wire cursor format
1292
+ * `"<snapshot>@<next_seq>"`. `null` snapshots stringify as
1293
+ * {@link MANIFEST_POINTER_EMPTY_SNAPSHOT} so the cursor is never the
1294
+ * empty string.
1295
+ *
1296
+ * @internal — exported for `query.test.ts`.
1297
+ */
1298
+ const serializeManifestPointer = (json) => `${json.snapshot ?? "none"}@${json.next_seq}`;
1299
+ /**
1300
+ * Returns the id iff `wire` carries exactly one clause and that
1301
+ * clause is `{op:"eq", field:"_id", value:<string>}` — the shape
1302
+ * `runRead` short-circuits to a single `Map.get`. Any other shape
1303
+ * (multi-clause, non-`eq` op, non-`_id` field, non-string value)
1304
+ * returns `undefined` and falls through to the scan path.
1305
+ *
1306
+ * Kernel-internal `_id`-shaped wires (built by `byId`,
1307
+ * `runByIdWithMeta`, `runInsert`) bypass the wire validator by
1308
+ * design (`_id` at the root is a wire-only rejection); this
1309
+ * recogniser matches the same shape so the fast-path stays
1310
+ * symmetric.
1311
+ *
1312
+ * @internal
1313
+ */
1314
+ const singleIdFromPredicate = (wire) => {
1315
+ if (wire === void 0) return;
1316
+ if (wire.clauses.length !== 1) return;
1317
+ const clause = wire.clauses[0];
1318
+ if (clause.op !== "eq" || clause.field !== "_id") return;
1319
+ return typeof clause.value === "string" ? clause.value : void 0;
1320
+ };
1321
+ /**
1322
+ * Build a `Query<T>` from a context + frozen state. Every modifier
1323
+ * returns a NEW `Query<T>` carrying merged state — the input state
1324
+ * is never mutated. Identity inequality with the input chain is
1325
+ * intentional.
1326
+ *
1327
+ * Validation happens at the public seams — `Query.where(p)`
1328
+ * normalises + validates the incoming fragment before merging into
1329
+ * `state.wire`. By the time `makeQuery` is reached from elsewhere
1330
+ * (`Collection.where`, `runAllWithMeta`, kernel-internal `_id`-shaped
1331
+ * wires from `byId` / `runByIdWithMeta` / `runInsert`), the wire is
1332
+ * already trusted.
1333
+ *
1334
+ * @example
1335
+ * ```ts
1336
+ * const q = makeQuery<Ticket>(ctx, { wire: undefined, order: undefined, limit: undefined });
1337
+ * const open = await q.where({ status: "open" }).order({ created_at: "desc" }).limit(10).all();
1338
+ * ```
1339
+ *
1340
+ * @internal
1341
+ */
1342
+ const makeQuery = (ctx, state) => {
1343
+ return {
1344
+ where: (p) => {
1345
+ const incoming = normalizePredicateArg(p);
1346
+ validateWire(incoming);
1347
+ return makeQuery(ctx, {
1348
+ ...state,
1349
+ wire: state.wire === void 0 ? incoming : mergePredicateWires(state.wire, incoming)
1350
+ });
1351
+ },
1352
+ order: (s) => makeQuery(ctx, {
1353
+ ...state,
1354
+ order: s
1355
+ }),
1356
+ limit: (n) => makeQuery(ctx, {
1357
+ ...state,
1358
+ limit: n
1359
+ }),
1360
+ first: async () => {
1361
+ const { rows } = await runRead(ctx, {
1362
+ ...state,
1363
+ limit: 1
1364
+ });
1365
+ return rows[0];
1366
+ },
1367
+ all: async () => {
1368
+ return (await runRead(ctx, state)).rows;
1369
+ },
1370
+ count: async () => {
1371
+ return (await runRead(ctx, state)).rows.length;
1372
+ },
1373
+ update: (patch) => runUpdate(ctx, state, patch),
1374
+ delete: () => runDelete(ctx, state)
1375
+ };
1376
+ };
1377
+ /**
1378
+ * Server-internal read entry surfacing the manifest-pointer cursor
1379
+ * and freshness flag alongside the materialised rows. The HTTP
1380
+ * router calls this directly so the read-response handler can pack
1381
+ * `_meta` onto the envelope; the public `Query<T>` terminals
1382
+ * destructure the rows out and discard the cursor to keep the
1383
+ * locked interface signature. Single-row routes (`GET /v1/c/:collection/:id`)
1384
+ * call this with `limit:1` and pick `rows[0]`.
1385
+ *
1386
+ * `state.wire` is assumed already validated — the public seam
1387
+ * (`Query.where(p)` → `normalizePredicateArg` → `validateWire`) is
1388
+ * the wire-arrival contract surface. Router callers parsing
1389
+ * `?where=` run `validateWire` themselves inside `parseWhereParam`,
1390
+ * keeping a single validation pass per wire.
1391
+ *
1392
+ * @internal
1393
+ */
1394
+ const runAllWithMeta = (ctx, state) => {
1395
+ return runRead(ctx, state);
1396
+ };
1397
+ /**
1398
+ * By-id read entry surfacing the same `ReadResult<T>` shape as
1399
+ * {@link runAllWithMeta} so the HTTP router can preserve the
1400
+ * `_meta` wire envelope while routing through the PK-lookup
1401
+ * fast-path. Mirrors {@link runAllWithMeta}'s signature; the
1402
+ * wire is built internally as a single-clause `{op:"eq",
1403
+ * field:"_id", value:id}` shape (same form as the `byId` helper in
1404
+ * `./collection.ts` and the `runInsert` duplicate-collision check)
1405
+ * which routes through `runRead`'s `singleIdFromPredicate`
1406
+ * short-circuit automatically.
1407
+ *
1408
+ * Bypasses {@link validateWire} — the wire is kernel-constructed,
1409
+ * never wire-submitted, so it would always pass the structural
1410
+ * rules. Skipping the validator also keeps this helper usable
1411
+ * from kernel-internal sites (`Collection<T>.get` etc.) without
1412
+ * tripping the wire-only rule that bans top-level `_id`.
1413
+ *
1414
+ * @internal — router uses this to preserve `_meta` envelope;
1415
+ * mirrors {@link runAllWithMeta} and {@link Collection.get}.
1416
+ */
1417
+ const runByIdWithMeta = (ctx, id) => {
1418
+ return runRead(ctx, {
1419
+ wire: { clauses: [{
1420
+ op: "eq",
1421
+ field: "_id",
1422
+ value: id
1423
+ }] },
1424
+ order: void 0,
1425
+ limit: 1
1426
+ });
1427
+ };
1428
+ /**
1429
+ * Build a fresh `Writer` bound to this collection's `current.json`.
1430
+ * Construction is zero-I/O (writer.ts:160) so we mint one per
1431
+ * `commit()` rather than caching on the chain — same writer object
1432
+ * shared across N commits would inherit retry-budget state we want
1433
+ * fresh per call.
1434
+ */
1435
+ const writerFor = (ctx) => new Writer({
1436
+ storage: ctx.storage,
1437
+ currentJsonKey: `${ctx.collectionPrefix}/current.json`,
1438
+ options: { indexes: ctx.indexes }
1439
+ });
1440
+ /**
1441
+ * `Collection.insert` / `Query.insert` implementation. Mints a UUIDv7 `_id`
1442
+ * when the caller omits it (or supplies an empty string); honours a
1443
+ * caller-supplied non-empty `_id`. On collision (the materialised
1444
+ * collection already carries that `_id`) throws
1445
+ * `BaerlyError{code:"Conflict"}` BEFORE issuing the writer round-trip
1446
+ * — matches the locked `Collection.insert` contract
1447
+ * (`packages/protocol/src/collection-api.ts:123–125`).
1448
+ *
1449
+ * The emitted `LogEntry` has `op:"I"` and `new === patch === {...doc, _id}`
1450
+ * (today's per-doc-replace model — `packages/protocol/src/log.ts:67–72`).
1451
+ *
1452
+ * @throws BaerlyError code="Conflict" — `_id` collision (pre-commit check) or
1453
+ * CAS retry budget exhausted inside `Writer.commit()`.
1454
+ * @throws BaerlyError code="SchemaError" — from the per-collection
1455
+ * `SchemaValidator` threaded via {@link Db.collectionReadContext}.
1456
+ *
1457
+ * @internal — exported for `Collection.insert` in `./collection.ts` to delegate
1458
+ * without duplicating the auto-id / collision-check /
1459
+ * commit pipeline.
1460
+ */
1461
+ const runInsert = async (ctx, doc) => {
1462
+ const supplied = doc["_id"];
1463
+ const _id = typeof supplied === "string" && supplied.length > 0 ? supplied : uuidv7();
1464
+ const body = {
1465
+ ...doc,
1466
+ _id
1467
+ };
1468
+ if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, body, {
1469
+ collection: ctx.collectionName,
1470
+ verb: "insert"
1471
+ });
1472
+ if ((await runRead(ctx, {
1473
+ wire: { clauses: [{
1474
+ op: "eq",
1475
+ field: "_id",
1476
+ value: _id
1477
+ }] },
1478
+ order: void 0,
1479
+ limit: 1
1480
+ })).rows.length > 0) throw new BaerlyError("Conflict", `Query.insert: _id ${JSON.stringify(_id)} already exists in collection ${JSON.stringify(ctx.collectionName)}`);
1481
+ if (ctx.txCtx !== void 0) {
1482
+ assertTxBindMatches(ctx);
1483
+ ctx.txCtx.mutations.push({
1484
+ op: "I",
1485
+ docId: _id,
1486
+ body
1487
+ });
1488
+ return { _id };
1489
+ }
1490
+ await writerFor(ctx).commit({
1491
+ op: "I",
1492
+ collection: ctx.collectionName,
1493
+ docId: _id,
1494
+ body
1495
+ });
1496
+ return { _id };
1497
+ };
1498
+ /**
1499
+ * `Query.update` implementation. Materialises the predicate/order/
1500
+ * limit-filtered match set, applies RFC 7386 `merge(prev, patch)`
1501
+ * per row, and emits one `op:"U"` `LogEntry` per affected `doc_id`
1502
+ * — one `Writer.commit()` round-trip apiece.
1503
+ *
1504
+ * Atomicity is per row, not across the N-row batch. The locked
1505
+ * contract (`packages/protocol/src/collection-api.ts:178–184`) is explicit on
1506
+ * this: all-or-nothing across multiple rows is what
1507
+ * `db.transaction(...)` exists to deliver.
1508
+ *
1509
+ * `replica_identity` defaults to `PATCH_ONLY` for every collection
1510
+ * today — emitted `U` entries carry `{ new, patch }` (equal) and
1511
+ * neither `old` nor `key_old`. Consumers rebuilding pre-images
1512
+ * under `PATCH_ONLY` need to maintain a shadow table — see
1513
+ * `packages/protocol/src/log.ts:102–118`.
1514
+ *
1515
+ * @throws BaerlyError code="Conflict" — any one row's CAS retry budget
1516
+ * exhausted inside `Writer.commit()`. The partial-progress
1517
+ * `modified` count is NOT returned in that case.
1518
+ * @throws BaerlyError code="SchemaError" — `merge(prev, patch)` produced
1519
+ * `undefined` (defensive — `Partial<T>` cannot be `null` at the
1520
+ * root in the type system).
1521
+ */
1522
+ const runUpdate = async (ctx, state, patch) => {
1523
+ const { rows } = await runRead(ctx, state);
1524
+ const tx = ctx.txCtx;
1525
+ if (tx !== void 0) assertTxBindMatches(ctx);
1526
+ let modified = 0;
1527
+ for (const doc of rows) {
1528
+ const merged = merge(doc, patch);
1529
+ if (merged === void 0) throw new BaerlyError("SchemaError", `Query.update: merge produced undefined for doc ${JSON.stringify(doc["_id"])}`);
1530
+ if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, merged, {
1531
+ collection: ctx.collectionName,
1532
+ verb: "update"
1533
+ });
1534
+ if (tx !== void 0) tx.mutations.push({
1535
+ op: "U",
1536
+ docId: String(doc["_id"]),
1537
+ body: merged
1538
+ });
1539
+ else await writerFor(ctx).commit({
1540
+ op: "U",
1541
+ collection: ctx.collectionName,
1542
+ docId: String(doc["_id"]),
1543
+ body: merged
1544
+ });
1545
+ modified++;
1546
+ }
1547
+ return { modified };
1548
+ };
1549
+ /**
1550
+ * `Collection.replace` implementation. Existence check via `runRead` over
1551
+ * a `byId`-shaped wire so the `singleIdFromPredicate` PK fast path
1552
+ * (`Map.get`) fires and any transaction-buffered insert of `id` is
1553
+ * visible. Missing row → `NotFound` directly (no Conflict-string
1554
+ * indirection through the router). Present row → emit a single
1555
+ * `op:"U"` `LogEntry` carrying `doc` as the post-image, with `_id`
1556
+ * forced to the requested `id` so doc identity is preserved across
1557
+ * replaces even if the supplied `doc._id` differs.
1558
+ *
1559
+ * @throws BaerlyError code="NotFound" — no row exists at `id`.
1560
+ * @throws BaerlyError code="SchemaError" — post-image rejected by
1561
+ * the collection's bound validator.
1562
+ * @throws BaerlyError code="Conflict" — writer CAS retry budget
1563
+ * exhausted.
1564
+ */
1565
+ const runReplaceById = async (ctx, id, doc) => {
1566
+ const { rows } = await runRead(ctx, {
1567
+ wire: { clauses: [{
1568
+ op: "eq",
1569
+ field: "_id",
1570
+ value: id
1571
+ }] },
1572
+ order: void 0,
1573
+ limit: void 0
1574
+ });
1575
+ if (rows.length === 0) throw new BaerlyError("NotFound", `No such row: ${id}`);
1576
+ const body = {
1577
+ ...doc,
1578
+ _id: id
1579
+ };
1580
+ if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, body, {
1581
+ collection: ctx.collectionName,
1582
+ verb: "replace"
1583
+ });
1584
+ if (ctx.txCtx !== void 0) {
1585
+ assertTxBindMatches(ctx);
1586
+ ctx.txCtx.mutations.push({
1587
+ op: "U",
1588
+ docId: id,
1589
+ body
1590
+ });
1591
+ return;
1592
+ }
1593
+ await writerFor(ctx).commit({
1594
+ op: "U",
1595
+ collection: ctx.collectionName,
1596
+ docId: id,
1597
+ body
1598
+ });
1599
+ };
1600
+ /**
1601
+ * `Query.delete` implementation. Tombstones every matched row with a
1602
+ * single `op:"D"` `LogEntry` per `doc_id`. `replica_identity` defaults
1603
+ * to `PATCH_ONLY`, so emitted `D` entries carry neither `new`/`patch`
1604
+ * nor `old`/`key_old`.
1605
+ * Consumers rebuilding pre-images under `PATCH_ONLY` need to
1606
+ * maintain a shadow table — see `packages/protocol/src/log.ts:102–118`.
1607
+ *
1608
+ * Atomicity is per row, not across the N-row batch — same shape as
1609
+ * `Query.update`. `db.transaction(...)` is where all-or-nothing
1610
+ * semantics live.
1611
+ *
1612
+ * @throws BaerlyError code="Conflict" — any one row's CAS retry budget
1613
+ * exhausted. The partial-progress `deleted` count is NOT returned
1614
+ * in that case.
1615
+ */
1616
+ const runDelete = async (ctx, state) => {
1617
+ const { rows } = await runRead(ctx, state);
1618
+ const tx = ctx.txCtx;
1619
+ if (tx !== void 0) assertTxBindMatches(ctx);
1620
+ let deleted = 0;
1621
+ for (const doc of rows) {
1622
+ if (tx !== void 0) tx.mutations.push({
1623
+ op: "D",
1624
+ docId: String(doc["_id"])
1625
+ });
1626
+ else await writerFor(ctx).commit({
1627
+ op: "D",
1628
+ collection: ctx.collectionName,
1629
+ docId: String(doc["_id"])
1630
+ });
1631
+ deleted++;
1632
+ }
1633
+ return { deleted };
1634
+ };
1635
+ /**
1636
+ * Runtime guard for the txCtx-Collection-name binding. The type system
1637
+ * already prevents the legitimate path (the body callback gets one
1638
+ * `Collection<T>`, no `Db`), so this only catches a bug where a stale
1639
+ * `Query<T>` outlives its `Collection<T>` and is somehow re-attached to a
1640
+ * transaction over a different collection.
1641
+ *
1642
+ * @throws BaerlyError code="Internal" — txCtx ↔ Collection name mismatch.
1643
+ */
1644
+ const assertTxBindMatches = (ctx) => {
1645
+ if (ctx.txCtx === void 0) return;
1646
+ if (ctx.txCtx.collection !== ctx.collectionName) throw new BaerlyError("Internal", `Transaction context bound to ${JSON.stringify(ctx.txCtx.collection)} but mutation issued on collection ${JSON.stringify(ctx.collectionName)}`);
1647
+ };
1648
+ /**
1649
+ * Load `current.json` fresh, walk `[0, next_seq)` in parallel, fold
1650
+ * per-`doc_id`, then apply predicate / order / limit in memory.
1651
+ *
1652
+ * Error mapping:
1653
+ * - `current.json` missing → empty result (collection not provisioned).
1654
+ * - `current.json` malformed → `InvalidResponse` (from `readCurrentJson`).
1655
+ * - log entry missing in `[0, next_seq)` → `Internal`.
1656
+ * - log entry malformed → `InvalidResponse`.
1657
+ */
1658
+ const runRead = async (ctx, state) => {
1659
+ const currentJsonKey = `${ctx.collectionPrefix}/current.json`;
1660
+ const head = await readCurrentJson(ctx.storage, currentJsonKey);
1661
+ const manifestPointer = head === null ? `${MANIFEST_POINTER_EMPTY_SNAPSHOT}@0` : serializeManifestPointer(head.json);
1662
+ const fresh = true;
1663
+ if (head === null) return {
1664
+ rows: [],
1665
+ manifestPointer,
1666
+ fresh
1667
+ };
1668
+ const plan = planQuery(state.wire, ctx.indexes);
1669
+ if (plan.kind === "index-walk") {
1670
+ let rows = await runIndexWalkPlan(ctx, head.json, state, plan);
1671
+ if (state.order !== void 0) rows = sortByOrderSpec(rows, state.order);
1672
+ if (state.limit !== void 0 && state.limit < rows.length) rows = rows.slice(0, state.limit);
1673
+ return {
1674
+ rows,
1675
+ manifestPointer,
1676
+ fresh
1677
+ };
1678
+ }
1679
+ const nextSeq = head.json.next_seq;
1680
+ const logSeqStart = logSeqStartOf(head.json);
1681
+ const baseDocs = head.json.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.json.snapshot, ctx.collectionName);
1682
+ const entries = await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, nextSeq);
1683
+ const docs = new Map(baseDocs);
1684
+ foldLogEntriesOnto(docs, entries, { collection: ctx.collectionName });
1685
+ const fastId = singleIdFromPredicate(state.wire);
1686
+ let rows;
1687
+ if (fastId !== void 0) {
1688
+ const hit = docs.get(fastId);
1689
+ rows = hit === void 0 ? [] : [hit];
1690
+ } else {
1691
+ rows = Array.from(docs.values());
1692
+ if (state.wire !== void 0) {
1693
+ const w = state.wire;
1694
+ rows = rows.filter((d) => matchesWire(w, d));
1695
+ }
1696
+ }
1697
+ if (state.order !== void 0) rows = sortByOrderSpec(rows, state.order);
1698
+ if (state.limit !== void 0 && state.limit < rows.length) rows = rows.slice(0, state.limit);
1699
+ return {
1700
+ rows,
1701
+ manifestPointer,
1702
+ fresh
1703
+ };
1704
+ };
1705
+ /**
1706
+ * Range-walk exclusive-lower sentinel. `Storage.list({startAfter})`
1707
+ * is strict-greater; to position the cursor PAST every entry whose
1708
+ * value-segment equals `ENCODE(lo)`, append a character that
1709
+ * lex-sorts strictly greater than every base-32 character (the
1710
+ * encoder alphabet is `[0-9a-v]`, topping out at `v` = 0x76) AND
1711
+ * strictly greater than the path separator `/` (0x2F).
1712
+ *
1713
+ * `~` (0x7E) satisfies both. The cursor `${eqPrefix}${ENCODE(lo)}/~`
1714
+ * lex-sorts strictly greater than the LARGEST possible key under
1715
+ * the `lo` value bucket but strictly less than the smallest key
1716
+ * under any bucket with a larger value-segment. The next LIST
1717
+ * result is the first entry with value-segment strictly greater
1718
+ * than `ENCODE(lo)` — exactly the exclusive-lower semantics we
1719
+ * want.
1720
+ */
1721
+ const RANGE_EXCLUSIVE_LOWER_SENTINEL = "~";
1722
+ /**
1723
+ * Bounded parallelism for `$in` multi-walk LISTs. Each batch of this
1724
+ * many `$in` values dispatches its `list()` calls concurrently; the
1725
+ * loop waits on the batch before starting the next.
1726
+ *
1727
+ * Picked low (8) to stay well under any cloud-provider per-call concurrency
1728
+ * ceiling while still amortising LIST round-trip latency on multi-value
1729
+ * `$in` queries. The planner's `IN_FANOUT_THRESHOLD` (50) caps the total
1730
+ * fan-out independently — see `packages/server/src/query-planner.ts`.
1731
+ */
1732
+ const IN_FANOUT_PARALLELISM = 8;
1733
+ /**
1734
+ * Execute an {@link IndexWalkPlan} against the bucket. Returns the
1735
+ * post-filtered, fully-resolved row set. The full original
1736
+ * `state.wire` is re-applied via `matchesWire(...)` after fetching
1737
+ * rows — this defends against stale index entries AND consumes the
1738
+ * planner's residue (range clauses, unrelated equality on
1739
+ * non-indexed fields) in one place.
1740
+ *
1741
+ * Storage shape (equality-only walks):
1742
+ * - Single-field walk (`equalityKeys.length === 1`): list
1743
+ * `<collectionPrefix>/index/<name>/<v0-b32>/`; each yielded key has
1744
+ * tail `<docId>.json` (single segment).
1745
+ * - Composite full walk (`equalityKeys.length === def.on.length`):
1746
+ * list `<collectionPrefix>/index/<name>/<v0-b32>/<v1-b32>/.../<vN-b32>/`;
1747
+ * each yielded key has tail `<docId>.json` (single segment).
1748
+ * - Composite partial-prefix walk (`equalityKeys.length <
1749
+ * def.on.length`): list `<collectionPrefix>/index/<name>/<v0-b32>/
1750
+ * .../<vM-b32>/`; each yielded key has tail
1751
+ * `<v{M+1}-b32>/.../<vN-b32>/<docId>.json` — MULTI-segment.
1752
+ * Split on `/` and take the last segment.
1753
+ *
1754
+ * Storage shape (T3, range / `$in` walks):
1755
+ * - Range walk (`plan.rangeOn !== undefined`): list
1756
+ * `<collectionPrefix>/index/<name>/<eq-segs>/` and break on the
1757
+ * first decoded value-segment past the upper bound. Lower
1758
+ * bound is enforced via `startAfter` (exclusive lower) or an
1759
+ * in-loop skip (inclusive lower) — see
1760
+ * {@link RANGE_EXCLUSIVE_LOWER_SENTINEL}.
1761
+ * - `$in` walk (`plan.inOn !== undefined`): one LIST per value,
1762
+ * with the equality prefix prepended to each, dispatched in
1763
+ * batches of {@link IN_FANOUT_PARALLELISM} `Promise.all`-style.
1764
+ * Doc-ids accumulate into a single Set (union semantics).
1765
+ *
1766
+ * Stale-row defence:
1767
+ * - An index entry pointing at a docId whose underlying doc has
1768
+ * since been updated to a different value (rebuild hasn't run)
1769
+ * is dropped by the in-memory `matchesWire(...)` re-check.
1770
+ * - An index entry pointing at a docId whose underlying doc has
1771
+ * been deleted (tombstone in the log) is dropped during the
1772
+ * fold (the `D` op removes it from the materialised set).
1773
+ *
1774
+ * @internal
1775
+ */
1776
+ const runIndexWalkPlan = async (ctx, head, state, plan) => {
1777
+ const encodedSegments = plan.equalityKeys.map((v) => encodeIndexValue(v));
1778
+ const eqPrefix = encodedSegments.length === 0 ? `${ctx.collectionPrefix}/index/${plan.indexName}/` : `${ctx.collectionPrefix}/index/${plan.indexName}/${encodedSegments.join("/")}/`;
1779
+ const docIdSet = /* @__PURE__ */ new Set();
1780
+ if (plan.rangeOn !== void 0) {
1781
+ const r = plan.rangeOn;
1782
+ const loEncoded = r.lo === void 0 ? void 0 : encodeIndexValue(r.lo);
1783
+ const hiEncoded = r.hi === void 0 ? void 0 : encodeIndexValue(r.hi);
1784
+ const startAfter = r.lo !== void 0 && !r.loInclusive ? `${eqPrefix}${loEncoded}/${RANGE_EXCLUSIVE_LOWER_SENTINEL}` : void 0;
1785
+ const listOpts = startAfter === void 0 ? {} : { startAfter };
1786
+ for await (const entry of ctx.storage.list(eqPrefix, listOpts)) {
1787
+ const tail = entry.key.slice(eqPrefix.length);
1788
+ const firstSlash = tail.indexOf("/");
1789
+ if (firstSlash < 0) continue;
1790
+ const valueSeg = tail.slice(0, firstSlash);
1791
+ if (loEncoded !== void 0 && valueSeg < loEncoded) continue;
1792
+ if (hiEncoded !== void 0) {
1793
+ if (r.hiInclusive ? valueSeg > hiEncoded : valueSeg >= hiEncoded) break;
1794
+ }
1795
+ const lastSlash = tail.lastIndexOf("/");
1796
+ const last = lastSlash === firstSlash ? tail.slice(firstSlash + 1) : tail.slice(lastSlash + 1);
1797
+ if (!last.endsWith(".json")) continue;
1798
+ const docId = last.slice(0, -5);
1799
+ if (docId.length === 0) continue;
1800
+ docIdSet.add(docId);
1801
+ }
1802
+ } else if (plan.inOn !== void 0) {
1803
+ const values = plan.inOn.values;
1804
+ const walkOne = async (value) => {
1805
+ const valPrefix = `${eqPrefix}${encodeIndexValue(value)}/`;
1806
+ const ids = [];
1807
+ for await (const entry of ctx.storage.list(valPrefix)) {
1808
+ const tail = entry.key.slice(valPrefix.length);
1809
+ if (!tail.endsWith(".json")) continue;
1810
+ const lastSlash = tail.lastIndexOf("/");
1811
+ const docId = lastSlash === -1 ? tail.slice(0, -5) : tail.slice(lastSlash + 1, -5);
1812
+ if (docId.length === 0) continue;
1813
+ ids.push(docId);
1814
+ }
1815
+ return ids;
1816
+ };
1817
+ for (let i = 0; i < values.length; i += IN_FANOUT_PARALLELISM) {
1818
+ const batch = values.slice(i, i + IN_FANOUT_PARALLELISM);
1819
+ const results = await Promise.all(batch.map(walkOne));
1820
+ for (const ids of results) for (const id of ids) docIdSet.add(id);
1821
+ }
1822
+ } else for await (const entry of ctx.storage.list(eqPrefix)) {
1823
+ const tail = entry.key.slice(eqPrefix.length);
1824
+ if (!tail.endsWith(".json")) continue;
1825
+ const lastSlash = tail.lastIndexOf("/");
1826
+ const docId = lastSlash === -1 ? tail.slice(0, -5) : tail.slice(lastSlash + 1, -5);
1827
+ if (docId.length === 0) continue;
1828
+ docIdSet.add(docId);
1829
+ }
1830
+ const docIds = Array.from(docIdSet);
1831
+ if (docIds.length === 0) return [];
1832
+ const matched = new Set(docIds);
1833
+ const baseDocs = head.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.snapshot, ctx.collectionName);
1834
+ const docs = /* @__PURE__ */ new Map();
1835
+ for (const id of matched) {
1836
+ const seeded = baseDocs.get(id);
1837
+ if (seeded !== void 0) docs.set(id, seeded);
1838
+ }
1839
+ const logSeqStart = logSeqStartOf(head);
1840
+ const nextSeq = head.next_seq;
1841
+ foldLogEntriesOnto(docs, await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, nextSeq), {
1842
+ collection: ctx.collectionName,
1843
+ docIdFilter: matched
1844
+ });
1845
+ const rows = [];
1846
+ const wire = state.wire;
1847
+ for (const doc of docs.values()) if (wire === void 0 || matchesWire(wire, doc)) rows.push(doc);
1848
+ return rows;
1849
+ };
1850
+ /**
1851
+ * Stable multi-key sort built from an `OrderSpec`. Keys are taken in
1852
+ * the spec's insertion order, which matches the caller's source-order
1853
+ * expectation. `Array.prototype.sort` is stable on Node 24+ and Workerd.
1854
+ *
1855
+ * Top-level fields only (locked at `OrderSpec<T>`).
1856
+ * Values are `DocumentValue` — string / number / boolean / object —
1857
+ * but only the primitive types are sensibly orderable; comparing two
1858
+ * objects falls through to "considered equal," which preserves the
1859
+ * stable-sort order of the input.
1860
+ */
1861
+ const sortByOrderSpec = (rows, spec) => {
1862
+ const entries = Object.entries(spec);
1863
+ return rows.toSorted((a, b) => {
1864
+ for (const [field, dir] of entries) {
1865
+ const av = a[field];
1866
+ const bv = b[field];
1867
+ if (av === bv) continue;
1868
+ if (av === void 0) return dir === "desc" ? 1 : -1;
1869
+ if (bv === void 0) return dir === "desc" ? -1 : 1;
1870
+ if (typeof av === "object" || typeof bv === "object") continue;
1871
+ const cmp = av < bv ? -1 : 1;
1872
+ return dir === "desc" ? -cmp : cmp;
1873
+ }
1874
+ return 0;
1875
+ });
1876
+ };
1877
+ //#endregion
1878
+ export { runReplaceById as a, lsnParts as c, runInsert as i, delay as l, runAllWithMeta as n, validateOrThrow as o, runByIdWithMeta as r, Writer as s, makeQuery as t };
1879
+
1880
+ //# sourceMappingURL=query-DcSbFLJt.js.map