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