@gusto/baerly-storage 0.6.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 (218) hide show
  1. package/README.md +47 -124
  2. package/dist/API.md +161 -512
  3. package/dist/CHANGELOG.md +1137 -378
  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-ypCm3zjt.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-wrVYf4bb.js → cloudflare-CKHYXccw.js} +61 -82
  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-Di_Q01qx.js → deploy-Obj4nE-Z.js} +10 -14
  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 +9 -14
  53. package/dist/dev-vite.js +11 -10
  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-Bx6xSNJj.d.ts → gcs-admin-Dso1HWQj.d.ts} +18 -14
  68. package/dist/gcs.d.ts +19 -7
  69. package/dist/gcs.js +1 -2
  70. package/dist/{goog4-signer-Z7KnJ1su.js → goog4-signer-CeLIABoE.js} +102 -92
  71. package/dist/goog4-signer-CeLIABoE.js.map +1 -0
  72. package/dist/{http-7zT29K3P.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-DP3ClvcA.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 +119 -92
  103. package/dist/node.js +3 -3
  104. package/dist/{observability-Ch-VQJyE.js → observability-C-ISCCLE.js} +1247 -326
  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-C4qgiXSg.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--LykAdl1.js → runtime-spec-B5mg3pHF.js} +189 -28
  120. package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
  121. package/dist/{s3-http-DD5gDc7t.d.ts → s3-http-DBC_wiCL.d.ts} +14 -8
  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-CqcKTjw9.js → sha256-4FfGQNPw.js} +9 -9
  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/{aws4fetch.esm-CXE5ZbAa.js → sigv4-sign-5IUflUD_.js} +143 -96
  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-BMFfDUI2.js → src-Actga-bO.js} +949 -363
  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-BV68pqwJ.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-BMZR8o6U.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 +90 -69
  152. package/dist/aws4fetch.esm-CXE5ZbAa.js.map +0 -1
  153. package/dist/bytes-BXdamO3L.js +0 -11
  154. package/dist/bytes-BXdamO3L.js.map +0 -1
  155. package/dist/cloudflare-wrVYf4bb.js.map +0 -1
  156. package/dist/config-B6nTy8e2.js +0 -3095
  157. package/dist/config-B6nTy8e2.js.map +0 -1
  158. package/dist/constants-CfeMWQWk.js +0 -222
  159. package/dist/constants-CfeMWQWk.js.map +0 -1
  160. package/dist/context-DRZ3tZ5l.js.map +0 -1
  161. package/dist/cost-_SE_SVgZ.js +0 -203
  162. package/dist/cost-_SE_SVgZ.js.map +0 -1
  163. package/dist/current-json-C6nhPOm1.js.map +0 -1
  164. package/dist/db-DjjthkTi.d.ts +0 -254
  165. package/dist/deploy-Di_Q01qx.js.map +0 -1
  166. package/dist/doctor-RWVRpvat.js +0 -102
  167. package/dist/doctor-RWVRpvat.js.map +0 -1
  168. package/dist/dump-m2vEYDNY.js +0 -94
  169. package/dist/dump-m2vEYDNY.js.map +0 -1
  170. package/dist/errors-Dfa3p78c.js +0 -78
  171. package/dist/errors-Dfa3p78c.js.map +0 -1
  172. package/dist/export-DenKwEQu.js +0 -401
  173. package/dist/export-DenKwEQu.js.map +0 -1
  174. package/dist/fsck-2Vq-7-e2.js +0 -279
  175. package/dist/fsck-2Vq-7-e2.js.map +0 -1
  176. package/dist/goog4-signer-Z7KnJ1su.js.map +0 -1
  177. package/dist/http-7zT29K3P.js.map +0 -1
  178. package/dist/http-transport-BTgVCY5r.js +0 -1250
  179. package/dist/http-transport-BTgVCY5r.js.map +0 -1
  180. package/dist/index-BHz92Acj.d.ts +0 -162
  181. package/dist/index-CEZKQsKt.d.ts +0 -1113
  182. package/dist/index-uE-w2dgj.d.ts +0 -115
  183. package/dist/indexes-Dn9hbGQG.d.ts +0 -22
  184. package/dist/inspect-BpYbH1DM.js +0 -133
  185. package/dist/inspect-BpYbH1DM.js.map +0 -1
  186. package/dist/log-tail-QWU4wlu-.js +0 -514
  187. package/dist/log-tail-QWU4wlu-.js.map +0 -1
  188. package/dist/maintenance-BGHGt2Yg.d.ts +0 -537
  189. package/dist/maintenance-DULFcpd1.js +0 -2144
  190. package/dist/maintenance-DULFcpd1.js.map +0 -1
  191. package/dist/maintenance-fEi-UZ2o.js +0 -1412
  192. package/dist/maintenance-fEi-UZ2o.js.map +0 -1
  193. package/dist/normalize-rjnZLwS4.js +0 -133
  194. package/dist/normalize-rjnZLwS4.js.map +0 -1
  195. package/dist/observability-Ch-VQJyE.js.map +0 -1
  196. package/dist/plan-C4qgiXSg.js.map +0 -1
  197. package/dist/query-C43r-6ib.js +0 -1773
  198. package/dist/query-C43r-6ib.js.map +0 -1
  199. package/dist/rebuild-index-BH1dc1p6.js +0 -81
  200. package/dist/rebuild-index-BH1dc1p6.js.map +0 -1
  201. package/dist/request-u0M51mhJ.js +0 -72
  202. package/dist/request-u0M51mhJ.js.map +0 -1
  203. package/dist/restore-D0VYWzfP.js +0 -778
  204. package/dist/restore-D0VYWzfP.js.map +0 -1
  205. package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
  206. package/dist/runtime-spec--LykAdl1.js.map +0 -1
  207. package/dist/sha256-CqcKTjw9.js.map +0 -1
  208. package/dist/shared-secret-DgEicd3x.js.map +0 -1
  209. package/dist/src-BMFfDUI2.js.map +0 -1
  210. package/dist/src-DYZ4H1aF.js +0 -392
  211. package/dist/src-DYZ4H1aF.js.map +0 -1
  212. package/dist/src-DvbTEya2.js +0 -536
  213. package/dist/src-DvbTEya2.js.map +0 -1
  214. package/dist/subcommand-BV68pqwJ.js.map +0 -1
  215. package/dist/time-DUqvFMHq.js.map +0 -1
  216. package/dist/usage-BMZR8o6U.js.map +0 -1
  217. package/dist/validate-DtljsCh1.js.map +0 -1
  218. package/dist/wire-izfGZDvr.js.map +0 -1
@@ -0,0 +1,3261 @@
1
+ import { t as CODE_RESOLUTIONS } from "./code-resolution-CL_7L0wS.js";
2
+ import { c as certifiedDeleteFloor, d as logSeqStartOf, f as mintGeneration, g as encodeJsonBytes, h as decodeJsonBytes, i as assertWellFormedSegment, l as createCurrentJson, n as assertNfcSegment, p as readCurrentJson, r as assertPathSegment, t as assertNameSegment, u as logDeleteFloorOf } from "./path-segment-DBXG26PW.js";
3
+ import { b as MAX_DOCUMENT_BYTES, f as LOG_FORWARD_PROBE_CAP, h as MAINTENANCE_PROFILE_CF_FREE, o as FORBIDDEN_MERGE_KEYS, x as MAX_KEY_BYTES } from "./constants-D3GSH3tc.js";
4
+ import { i as isWriteConflict, t as BaerlyError } from "./errors-7Rk1HGCE.js";
5
+ import { i as assertInsertIdType, n as normalizePredicateArg, r as assertDocumentValues, t as uuidv7 } from "./uuid-BuT_c404.js";
6
+ import { S as logObjectKey, _ as loadSnapshotAsMap, c as rowBytes, f as probeReadTail, g as walkLogRange, h as foldLogEntriesOnto, i as resolveFoldCeilings, l as findLogTail, m as probeTailFrom, n as isFoldViable, o as shouldFireMaintenance, p as probeTailChunk, s as projectSnapshot, t as dispatchWriteTick, v as isOwnCollection, x as markCallerFacing, y as callerFacingCheck } from "./maintenance-DevB6z4e.js";
7
+ import { n as timestamp, o as uuid, r as countKey } from "./time-DRxTP9iv.js";
8
+ import { r as currentRequestLedger } from "./ledger-Dj_bGgo0.js";
9
+ import { a as noopMetricsRecorder, i as runWithContext, r as getCurrentContext } from "./context-rlpSnHFA.js";
10
+ // packages/protocol/src/document-size.ts
11
+ const utf8Encoder = new TextEncoder();
12
+ const DOCUMENT_SIZE_RESOLUTION = `Keep each document at or under ${MAX_DOCUMENT_BYTES} bytes (1 MiB) of JSON: move large or growing data (attachments, long histories, arrays that keep growing) into rows of their own, or store blobs outside the database and keep a reference.`;
13
+ /**
14
+ * UTF-8 byte length of `json` when it is over `limit`, else `undefined`.
15
+ * Skips the encode when the string is short enough to decide it: a UTF-16
16
+ * code unit encodes to at most 3 bytes.
17
+ */
18
+ const jsonByteLengthAbove = (json, limit) => {
19
+ if (json.length * 3 <= limit) return;
20
+ const bytes = utf8Encoder.encode(json).byteLength;
21
+ return bytes > limit ? bytes : void 0;
22
+ };
23
+ /**
24
+ * Refuse a post-image larger than {@link MAX_DOCUMENT_BYTES} once encoded
25
+ * as stored (`encodeJsonBytes`, which sorts nothing, so key order does not
26
+ * change the size). Call it on the whole document a write would commit,
27
+ * not on an update patch: a small patch can still grow a row past the cap.
28
+ * A row already stored larger is not checked here; only a write producing
29
+ * an over-cap post-image is refused.
30
+ *
31
+ * I/O-free. The value must already be in the JSON document domain (see
32
+ * `assertDocumentValues`); a value `JSON.stringify` cannot encode
33
+ * throws its own error.
34
+ *
35
+ * @param verb the calling verb, used as the message prefix.
36
+ * @throws BaerlyError code="InvalidConfig" — the encoded post-image is over
37
+ * the cap. The message states its size and the limit.
38
+ */
39
+ const assertDocumentSize = (value, verb) => {
40
+ const bytes = jsonByteLengthAbove(JSON.stringify(value), MAX_DOCUMENT_BYTES);
41
+ if (bytes !== void 0) throw new BaerlyError("InvalidConfig", `${verb}: the document encodes to ${bytes} bytes of JSON, over the ${MAX_DOCUMENT_BYTES}-byte (1 MiB) document limit`, { resolution: DOCUMENT_SIZE_RESOLUTION });
42
+ };
43
+ // packages/protocol/src/json.ts
44
+ /**
45
+ * Structural equality of two JSON values.
46
+ *
47
+ * Both inputs must already be JSON-normalized, i.e. the result of a
48
+ * `JSON.parse` — typically `JSON.parse(JSON.stringify(body))` compared
49
+ * against a stored row decoded from JSON. The round-trip drops
50
+ * `undefined` properties (as the write path's encoder does) and turns
51
+ * `-0` into `0`; that normalization is the caller's responsibility.
52
+ * Raw inputs holding `undefined` or `-0` are outside the contract.
53
+ *
54
+ * Uses an explicit work stack so comparison does not consume the
55
+ * JavaScript call stack with each nesting level. No depth cap is enforced.
56
+ *
57
+ * - Object key order is ignored; the key sets must match exactly.
58
+ * - Arrays compare element-wise in order, and an array is never equal
59
+ * to an object (`[1]` vs `{"0":1}` is `false`).
60
+ * - Primitives compare with `===`.
61
+ *
62
+ * Deliberately not `deepEqualDocumentValue`, which cannot tell an array
63
+ * from an index-keyed object.
64
+ */
65
+ function jsonValueEqual(a, b) {
66
+ const pending = [[a, b]];
67
+ while (pending.length > 0) {
68
+ const [left, right] = pending.pop();
69
+ if (left === right) continue;
70
+ if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
71
+ if (Array.isArray(left)) {
72
+ if (!Array.isArray(right) || left.length !== right.length) return false;
73
+ for (let i = 0; i < left.length; i++) pending.push([left[i], right[i]]);
74
+ continue;
75
+ }
76
+ if (Array.isArray(right)) return false;
77
+ const keys = Object.keys(left);
78
+ if (keys.length !== Object.keys(right).length) return false;
79
+ for (const key of keys) {
80
+ if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
81
+ pending.push([left[key], right[key]]);
82
+ }
83
+ }
84
+ return true;
85
+ }
86
+ const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
87
+ /**
88
+ * Apply a JSON Merge Patch to a document, exactly as RFC 7396 §2 defines
89
+ * it. This is what `update` commits: `applyMergePatch(row, patch)`.
90
+ *
91
+ * An object patch merges key by key into the target, or into `{}` when
92
+ * the target is absent or not an object. A `null` member deletes that
93
+ * key, at every depth, so a patch never stores a `null` member: under an
94
+ * absent field, `{ meta: { a: 1, b: null } }` stores `meta: { a: 1 }`.
95
+ * A scalar or array patch replaces the target whole; arrays are opaque
96
+ * values, so a `null` inside one is kept. An `undefined` member is
97
+ * absent, as in the patch's JSON form.
98
+ *
99
+ * Two values outside RFC 7396's JSON domain: an `undefined` patch is the
100
+ * identity (returns `target`), and a `null` patch at the root returns
101
+ * `undefined`, since a document cannot be `null`.
102
+ *
103
+ * `__proto__`, `constructor` and `prototype` members are skipped
104
+ * (`FORBIDDEN_MERGE_KEYS`). Recursion follows the patch, whose depth
105
+ * `assertDocumentValues` caps at `MAX_DOCUMENT_DEPTH` before `update`
106
+ * applies it.
107
+ */
108
+ function applyMergePatch(target, patch) {
109
+ if (patch === void 0) return target;
110
+ if (patch === null) return;
111
+ if (!isPlainObject(patch)) return patch;
112
+ const combined = isPlainObject(target) ? { ...target } : {};
113
+ const members = patch;
114
+ for (const key of Object.keys(members)) {
115
+ if (FORBIDDEN_MERGE_KEYS.has(key)) continue;
116
+ const value = members[key];
117
+ if (value === void 0) continue;
118
+ if (value === null) delete combined[key];
119
+ else combined[key] = applyMergePatch(combined[key], value);
120
+ }
121
+ return combined;
122
+ }
123
+ // packages/protocol/src/query/matches.ts
124
+ /** Follow a split dotted path from `doc`; `undefined` when it cannot be consumed. */
125
+ const walkPath = (doc, segments) => {
126
+ let cursor = doc;
127
+ for (const segment of segments) {
128
+ if (cursor === void 0 || cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) return;
129
+ cursor = cursor[segment];
130
+ }
131
+ return cursor;
132
+ };
133
+ /**
134
+ * Compile a validated wire-form predicate into a per-document test that
135
+ * agrees with {@link matchesWire} on every document. Each dotted clause
136
+ * path is split once here rather than once per document, so a filter
137
+ * over n rows pays one split per clause instead of n. Clause order,
138
+ * path walk and clause matchers are {@link matchesWire}'s.
139
+ *
140
+ * Same pre-condition as {@link matchesWire}: `wire` has passed
141
+ * {@link validateWire}.
142
+ *
143
+ * @example
144
+ * ```ts
145
+ * const open = compileWire({ clauses: [{ op: "eq", field: "meta.state", value: "open" }] });
146
+ * docs.filter(open);
147
+ * ```
148
+ */
149
+ const compileWire = (wire) => {
150
+ const compiled = wire.clauses.map((clause) => ({
151
+ clause,
152
+ field: clause.field,
153
+ segments: clause.field.includes(".") ? clause.field.split(".") : void 0
154
+ }));
155
+ return (doc) => {
156
+ for (const { clause, field, segments } of compiled) if (!matchesClause(clause, segments === void 0 ? doc[field] : walkPath(doc, segments))) return false;
157
+ return true;
158
+ };
159
+ };
160
+ const matchesClause = (clause, actual) => {
161
+ switch (clause.op) {
162
+ case "eq": return matchesEq(clause.value, actual);
163
+ case "in": return matchesIn(clause.value, actual);
164
+ case "gt": return compareGT(actual, clause.value, false);
165
+ case "gte": return compareGT(actual, clause.value, true);
166
+ case "lt": return compareLT(actual, clause.value, false);
167
+ case "lte": return compareLT(actual, clause.value, true);
168
+ }
169
+ };
170
+ const matchesEq = (expected, actual) => {
171
+ if (typeof expected === "object") {
172
+ if (actual === void 0 || actual === null || typeof actual !== "object" || Array.isArray(actual)) return false;
173
+ for (const subKey of Object.keys(expected)) {
174
+ const subExpected = expected[subKey];
175
+ if (subExpected === void 0) continue;
176
+ const subActual = actual[subKey];
177
+ if (!matchesEq(subExpected, subActual)) return false;
178
+ }
179
+ return true;
180
+ }
181
+ return expected === actual;
182
+ };
183
+ const matchesIn = (members, actual) => {
184
+ for (const m of members) if (typeof m === "object") {
185
+ if (matchesEq(m, actual)) return true;
186
+ } else if (m === actual) return true;
187
+ return false;
188
+ };
189
+ const compareGT = (actual, bound, inclusive) => {
190
+ if (typeof bound === "string") return typeof actual === "string" && (inclusive ? actual >= bound : actual > bound);
191
+ if (typeof bound === "number") return typeof actual === "number" && (inclusive ? actual >= bound : actual > bound);
192
+ return false;
193
+ };
194
+ const compareLT = (actual, bound, inclusive) => {
195
+ if (typeof bound === "string") return typeof actual === "string" && (inclusive ? actual <= bound : actual < bound);
196
+ if (typeof bound === "number") return typeof actual === "number" && (inclusive ? actual <= bound : actual < bound);
197
+ return false;
198
+ };
199
+ // packages/protocol/src/query/_internals.ts
200
+ /** @internal Same primitive type for comparison purposes. */
201
+ const sameComparableType = (a, b) => typeof a === "string" && typeof b === "string" || typeof a === "number" && typeof b === "number";
202
+ /**
203
+ * @internal Returns negative / zero / positive for a<b / a==b / a>b.
204
+ */
205
+ const compareScalar = (a, b) => {
206
+ if (typeof a === "number" && typeof b === "number") return a - b;
207
+ if (typeof a === "string" && typeof b === "string") {
208
+ if (a < b) return -1;
209
+ if (a > b) return 1;
210
+ return 0;
211
+ }
212
+ return 0;
213
+ };
214
+ /** @internal Render a predicate path for use in error messages. */
215
+ const formatPath = (path) => path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(".");
216
+ /**
217
+ * Recursive structural equality for `DocumentValue` values. Exported so
218
+ * `./satisfiable.ts` and other callers reuse the same comparison rule
219
+ * the validator + merger already trust. Two
220
+ * values `a` and `b` are equal iff:
221
+ *
222
+ * - they are reference-equal (covers primitives and object identity);
223
+ * - or they are both non-`null` objects with the same key set, and
224
+ * every value pair is recursively equal.
225
+ *
226
+ * Arrays are out-of-band for `DocumentValue`; this function rejects
227
+ * them implicitly via the same key-set walk (an array reads as an
228
+ * object with numeric-string keys plus a `length` exposure that
229
+ * `Object.keys` happens to skip — defensive callers should still gate
230
+ * with `Array.isArray` first).
231
+ */
232
+ const deepEqualDocumentValue = (a, b) => {
233
+ if (a === b) return true;
234
+ if (typeof a !== "object" || typeof b !== "object") return false;
235
+ const aKeys = Object.keys(a);
236
+ const bKeys = Object.keys(b);
237
+ if (aKeys.length !== bKeys.length) return false;
238
+ for (const key of aKeys) {
239
+ if (!(key in b)) return false;
240
+ const aSub = a[key];
241
+ const bSub = b[key];
242
+ if (aSub === void 0 || bSub === void 0) return false;
243
+ if (!deepEqualDocumentValue(aSub, bSub)) return false;
244
+ }
245
+ return true;
246
+ };
247
+ // packages/protocol/src/query/satisfiable.ts
248
+ /**
249
+ * Per-field satisfiability check for a {@link PredicateWire}. Groups
250
+ * clauses by field, then runs the same logic the pre-redesign
251
+ * `assertOpObjectSatisfiable` ran on a single op-object — but
252
+ * generalised across N clauses on the same field (the wire merger
253
+ * concatenates lists without coalescing).
254
+ *
255
+ * Triggers:
256
+ * - Two `eq` clauses on the same field with different values →
257
+ * `InvalidConfig` (the same conflict that pre-redesign
258
+ * `mergePredicates` threw on shared primitive keys).
259
+ * - Range bounds with `lo > hi` (or `lo == hi` with strict on
260
+ * either side) → `UnsatisfiablePredicate`.
261
+ * - `eq` value outside the residual range interval or absent from
262
+ * every `in` set on the same field → `UnsatisfiablePredicate`.
263
+ * - `in` sets that intersect to empty across multiple clauses →
264
+ * `UnsatisfiablePredicate`.
265
+ *
266
+ * Used by both `./validate.ts` (wire-arrival check) and
267
+ * `./merge.ts` (post-merge re-check, kept in lockstep).
268
+ */
269
+ const groupByField = (wire) => {
270
+ const out = /* @__PURE__ */ new Map();
271
+ for (const clause of wire.clauses) {
272
+ let group = out.get(clause.field);
273
+ if (group === void 0) {
274
+ group = {
275
+ eqs: [],
276
+ ins: []
277
+ };
278
+ out.set(clause.field, group);
279
+ }
280
+ applyClause(group, clause.field, clause);
281
+ }
282
+ return out;
283
+ };
284
+ const applyClause = (group, field, clause) => {
285
+ switch (clause.op) {
286
+ case "eq":
287
+ group.eqs.push(clause.value);
288
+ return;
289
+ case "in":
290
+ group.ins.push(clause.value);
291
+ return;
292
+ case "gt":
293
+ tightenLower(group, field, clause.value, false);
294
+ return;
295
+ case "gte":
296
+ tightenLower(group, field, clause.value, true);
297
+ return;
298
+ case "lt":
299
+ tightenUpper(group, field, clause.value, false);
300
+ return;
301
+ case "lte":
302
+ tightenUpper(group, field, clause.value, true);
303
+ return;
304
+ }
305
+ };
306
+ const tightenLower = (group, field, value, inclusive) => {
307
+ if (group.lo === void 0) {
308
+ group.lo = {
309
+ value,
310
+ inclusive
311
+ };
312
+ return;
313
+ }
314
+ if (!sameComparableType(group.lo.value, value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has type-incompatible lower bounds (${JSON.stringify(group.lo.value)} vs ${JSON.stringify(value)}).`);
315
+ const c = compareScalar(group.lo.value, value);
316
+ if (c < 0 || c === 0 && inclusive === false && group.lo.inclusive === true) group.lo = {
317
+ value,
318
+ inclusive
319
+ };
320
+ };
321
+ const tightenUpper = (group, field, value, inclusive) => {
322
+ if (group.hi === void 0) {
323
+ group.hi = {
324
+ value,
325
+ inclusive
326
+ };
327
+ return;
328
+ }
329
+ if (!sameComparableType(group.hi.value, value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has type-incompatible upper bounds (${JSON.stringify(group.hi.value)} vs ${JSON.stringify(value)}).`);
330
+ const c = compareScalar(group.hi.value, value);
331
+ if (c > 0 || c === 0 && inclusive === false && group.hi.inclusive === true) group.hi = {
332
+ value,
333
+ inclusive
334
+ };
335
+ };
336
+ const intersectInSets = (sets) => {
337
+ if (sets.length === 0) return [];
338
+ let acc = sets[0];
339
+ for (let i = 1; i < sets.length; i++) {
340
+ const next = [];
341
+ for (const a of acc) for (const b of sets[i]) if (deepEqualDocumentValue(a, b)) {
342
+ next.push(a);
343
+ break;
344
+ }
345
+ acc = next;
346
+ }
347
+ return acc;
348
+ };
349
+ /**
350
+ * Check that every per-field clause group on `wire` is jointly
351
+ * satisfiable. Throws `BaerlyError{code:"UnsatisfiablePredicate"}`
352
+ * (or `"InvalidConfig"` for conflicting `eq` clauses) on the
353
+ * first contradiction. Returns `void` on success.
354
+ */
355
+ const assertWireSatisfiable = (wire) => {
356
+ const groups = groupByField(wire);
357
+ for (const [field, group] of groups) {
358
+ if (group.eqs.length > 1) {
359
+ for (let i = 1; i < group.eqs.length; i++) if (!deepEqualDocumentValue(group.eqs[0], group.eqs[i])) throw new BaerlyError("InvalidConfig", `Conflicting equality clauses on field ${formatPath([field])} (${JSON.stringify(group.eqs[0])} vs ${JSON.stringify(group.eqs[i])}). Predicate chains must agree on shared equality.`);
360
+ }
361
+ const eq = group.eqs[0];
362
+ if (group.lo !== void 0 && group.hi !== void 0 && sameComparableType(group.lo.value, group.hi.value)) {
363
+ const c = compareScalar(group.lo.value, group.hi.value);
364
+ if (c > 0 || c === 0 && (!group.lo.inclusive || !group.hi.inclusive)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has empty interval (lo=${JSON.stringify(group.lo.value)} ${group.lo.inclusive ? "gte" : "gt"}, hi=${JSON.stringify(group.hi.value)} ${group.hi.inclusive ? "lte" : "lt"}).`);
365
+ }
366
+ if (eq !== void 0) {
367
+ if (group.lo !== void 0) {
368
+ if (!sameComparableType(eq, group.lo.value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} (${typeof eq}) is type-incompatible with lower bound ${JSON.stringify(group.lo.value)} (${typeof group.lo.value}); range ops require matching primitive types.`);
369
+ const c = compareScalar(eq, group.lo.value);
370
+ if (c < 0 || c === 0 && !group.lo.inclusive) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} excluded by lower bound ${JSON.stringify(group.lo.value)} (${group.lo.inclusive ? "gte" : "gt"}).`);
371
+ }
372
+ if (group.hi !== void 0) {
373
+ if (!sameComparableType(eq, group.hi.value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} (${typeof eq}) is type-incompatible with upper bound ${JSON.stringify(group.hi.value)} (${typeof group.hi.value}); range ops require matching primitive types.`);
374
+ const c = compareScalar(eq, group.hi.value);
375
+ if (c > 0 || c === 0 && !group.hi.inclusive) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} excluded by upper bound ${JSON.stringify(group.hi.value)} (${group.hi.inclusive ? "lte" : "lt"}).`);
376
+ }
377
+ if (group.ins.length > 0) for (const set of group.ins) {
378
+ let found = false;
379
+ for (const m of set) if (deepEqualDocumentValue(eq, m)) {
380
+ found = true;
381
+ break;
382
+ }
383
+ if (!found) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} not present in in() set.`);
384
+ }
385
+ }
386
+ if (group.ins.length > 1) {
387
+ if (intersectInSets(group.ins).length === 0) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has empty in() intersection across multiple clauses.`);
388
+ }
389
+ }
390
+ };
391
+ // packages/protocol/src/query/merge.ts
392
+ /**
393
+ * AND-merge two validated wire predicates. Powers chained
394
+ * `Query<T>.where(...).where(...)`.
395
+ */
396
+ /**
397
+ * AND-merge two validated wire predicates. The result accepts a
398
+ * document iff both `a` and `b` would accept it.
399
+ *
400
+ * Wire-level: clause lists concatenate. The per-field satisfiability
401
+ * check runs across the combined list, surfacing
402
+ * `BaerlyError{code:"UnsatisfiablePredicate"}` on empty residual
403
+ * intervals / empty `in()` intersections / `eq` outside the merged
404
+ * interval, and `BaerlyError{code:"InvalidConfig"}` on conflicting
405
+ * `eq` clauses for the same field (mirrors the pre-redesign
406
+ * conflict-on-shared-keys semantics).
407
+ *
408
+ * @example
409
+ * ```ts
410
+ * mergePredicateWires(
411
+ * { clauses: [{ op: "eq", field: "status", value: "open" }] },
412
+ * { clauses: [{ op: "eq", field: "priority", value: "p1" }] },
413
+ * );
414
+ * // → { clauses: [
415
+ * // { op: "eq", field: "status", value: "open" },
416
+ * // { op: "eq", field: "priority", value: "p1" },
417
+ * // ] }
418
+ *
419
+ * mergePredicateWires(
420
+ * { clauses: [{ op: "eq", field: "status", value: "open" }] },
421
+ * { clauses: [{ op: "eq", field: "status", value: "closed" }] },
422
+ * );
423
+ * // throws BaerlyError{InvalidConfig}: conflicting equality clauses on "status"
424
+ *
425
+ * mergePredicateWires(
426
+ * { clauses: [{ op: "gt", field: "x", value: 10 }] },
427
+ * { clauses: [{ op: "lt", field: "x", value: 5 }] },
428
+ * );
429
+ * // throws BaerlyError{UnsatisfiablePredicate}: empty interval
430
+ * ```
431
+ */
432
+ const mergePredicateWires = (a, b) => {
433
+ const merged = { clauses: [...a.clauses, ...b.clauses] };
434
+ assertWireSatisfiable(merged);
435
+ return merged;
436
+ };
437
+ // packages/protocol/src/query/validate.ts
438
+ /**
439
+ * Wire predicate validator. Walks a {@link PredicateWire} and throws
440
+ * on a structurally bad clause (`BaerlyError{code:"InvalidConfig"}`)
441
+ * or a per-field clause group that contradicts itself
442
+ * (`BaerlyError{code:"UnsatisfiablePredicate"}`).
443
+ *
444
+ * The object-form normaliser at `./normalize.ts` enforces shape on
445
+ * the way in (rejecting `$`-keys / non-scalars / null / undefined);
446
+ * the callback builder at `./builder.ts` enforces shape via the
447
+ * type system. This validator is the wire-arrival check: it runs
448
+ * over already-normalised clauses, defending against raw-`fetch`
449
+ * callers who bypass the typed seam and submit arbitrary JSON.
450
+ *
451
+ * Companion modules: `./matches.ts` (evaluator), `./merge.ts`
452
+ * (AND-merge). Shared helpers live in `./_internals.ts`.
453
+ */
454
+ const OP_NAMES = [
455
+ "eq",
456
+ "gt",
457
+ "gte",
458
+ "lt",
459
+ "lte",
460
+ "in"
461
+ ];
462
+ const RANGE_OPS = [
463
+ "gt",
464
+ "gte",
465
+ "lt",
466
+ "lte"
467
+ ];
468
+ /**
469
+ * Validate a normalised predicate wire. Throws
470
+ * `BaerlyError{code:"InvalidConfig"}` on a structurally bad clause,
471
+ * or `BaerlyError{code:"UnsatisfiablePredicate"}` when a clause
472
+ * group on one field contradicts itself.
473
+ *
474
+ * Returns the wire unchanged on success — callers can thread the
475
+ * validated wire forward.
476
+ *
477
+ * @example
478
+ * ```ts
479
+ * validateWire({ clauses: [{ op: "eq", field: "status", value: "open" }] }); // ok
480
+ * validateWire({ clauses: [{ op: "in", field: "priority", value: [] }] }); // throws UnsatisfiablePredicate
481
+ * validateWire({ clauses: [{ op: "eq", field: "_id", value: "x" }] }); // throws InvalidConfig (top-level _id)
482
+ * ```
483
+ */
484
+ const validateWire = (wire) => {
485
+ if (wire === null || typeof wire !== "object" || !Array.isArray(wire.clauses)) throw new BaerlyError("InvalidConfig", `Predicate wire must be an object with a "clauses" array.`);
486
+ for (let i = 0; i < wire.clauses.length; i++) validateClause(wire.clauses[i], i);
487
+ assertWireSatisfiable(wire);
488
+ return wire;
489
+ };
490
+ const validateClause = (clause, index) => {
491
+ if (clause === null || typeof clause !== "object") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} must be an object — got ${JSON.stringify(clause)}.`);
492
+ const { op, field, value } = clause;
493
+ if (typeof op !== "string" || !OP_NAMES.includes(op)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} has unsupported op ${JSON.stringify(op)} — supported: ${OP_NAMES.join(" / ")}.`);
494
+ if (typeof field !== "string" || field.length === 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} has empty / non-string field.`);
495
+ if (field === "_id" || field.startsWith("_id.")) throw new BaerlyError("InvalidConfig", "Predicates may not key on \"_id\"; use .get(id) / .update(id, patch) / .replace(id, doc) / .delete(id) instead.");
496
+ if (op === "in") {
497
+ if (!Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} (op="in", field=${JSON.stringify(field)}) must carry an array value.`);
498
+ if (value.length === 0) throw new BaerlyError("UnsatisfiablePredicate", `Predicate clause at index ${index} (op="in", field=${JSON.stringify(field)}) has empty value array — no document can match.`);
499
+ for (let i = 0; i < value.length; i++) validateMemberValue(value[i], field, index, i);
500
+ return;
501
+ }
502
+ if (Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} (op=${JSON.stringify(op)}, field=${JSON.stringify(field)}) must carry a primitive value, got an array — only op="in" accepts arrays.`);
503
+ if (RANGE_OPS.includes(op)) {
504
+ validateRangeBound(value, field, index);
505
+ return;
506
+ }
507
+ validateScalar(value, field, index);
508
+ };
509
+ const validateMemberValue = (value, field, clauseIndex, memberIndex) => {
510
+ if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is ${value === null ? "null" : "undefined"} — members must be string / number / boolean / nested object.`);
511
+ if (Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is an array — members must be string / number / boolean / nested object.`);
512
+ const t = typeof value;
513
+ if (t === "object") return;
514
+ if (t !== "string" && t !== "number" && t !== "boolean") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} has unsupported type ${JSON.stringify(t)} — must be string / number / boolean / nested object.`);
515
+ if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
516
+ };
517
+ const validateScalar = (value, field, clauseIndex) => {
518
+ if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value is ${value === null ? "null" : "undefined"} — terminal values must be string / number / boolean / nested object.`);
519
+ const t = typeof value;
520
+ if (t === "object") return;
521
+ if (t !== "string" && t !== "number" && t !== "boolean") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value has unsupported type ${JSON.stringify(t)} — must be string / number / boolean / nested object.`);
522
+ if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
523
+ };
524
+ const validateRangeBound = (value, field, clauseIndex) => {
525
+ if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is ${value === null ? "null" : "undefined"} — range bounds must be string or finite number.`);
526
+ const t = typeof value;
527
+ if (t === "boolean") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is a boolean — range bounds must be string or finite number (booleans are not ordered).`);
528
+ if (t === "object") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is a nested object — range bounds must be string or finite number.`);
529
+ if (t !== "string" && t !== "number") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) has unsupported type ${JSON.stringify(t)} — must be string or finite number.`);
530
+ if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
531
+ };
532
+ // packages/server/src/doc-id.ts
533
+ /**
534
+ * Resolution for a non-NFC `_id`. A row stored under one by an earlier
535
+ * release stays readable and deletable, so it is migrated by copy.
536
+ */
537
+ const DOC_ID_NFC_RESOLUTION = "Pass id.normalize(\"NFC\") for a new _id. To migrate a stored non-NFC row, insert a copy under a fresh NFC id that is not canonically equivalent to the original (for example, omit _id for a UUID), then delete the original.";
538
+ /**
539
+ * Resolution for an `_id` with an unpaired surrogate. A row stored under
540
+ * one by an earlier release stays readable and deletable in-process, so it
541
+ * is migrated by copy.
542
+ */
543
+ const DOC_ID_WELL_FORMED_RESOLUTION = "Pass an _id with no unpaired UTF-16 surrogate (id.isWellFormed() is true), or omit _id for a UUID. To migrate a stored row with such an _id, read it by _id, remove _id from the copy so insert generates a fresh UUID, then delete the original.";
544
+ /**
545
+ * Resolution for a point read whose id no row can be stored under.
546
+ */
547
+ const READ_ID_RESOLUTION = "Pass the _id string of a stored row. A valid _id is non-empty, at most 256 UTF-8 bytes, has no \"/\" or control characters, does not start with \"_\", and is not \".\" or \"..\".";
548
+ /**
549
+ * Guard an `_id` a write is about to store a row under: an insert, a
550
+ * replace, an update, or any `I` / `U` commit. The `_id` analogue of
551
+ * `assertKeySegment` (`db.ts`).
552
+ *
553
+ * Applies {@link assertStoredDocId}, then requires the id to be
554
+ * well-formed UTF-16 (no unpaired surrogate, which no URL or S3 key can
555
+ * carry) and in Unicode Normalization Form C (`id === id.normalize("NFC")`),
556
+ * so each canonical-equivalence class (NFC `é` and NFD `e` + U+0301) has one
557
+ * spelling and one byte form. R2 stores canonically-equivalent keys as one
558
+ * object, so any object a future format keys by `_id` (an index-aware
559
+ * snapshot, say) would otherwise merge two rows whose ids differ only by
560
+ * normalization; the rule keeps that door open, and loosening it later is
561
+ * not a breaking change. Case and compatibility variants (`A` / `a`, `fi` / `fi`)
562
+ * are distinct NFC strings and stay distinct ids.
563
+ *
564
+ * @throws BaerlyError code="InvalidConfig" — the id breaks the key-segment
565
+ * rule, holds an unpaired surrogate, or is not NFC.
566
+ */
567
+ const assertDocId = (id) => {
568
+ assertStoredDocId(id);
569
+ assertWellFormedSegment(id, "_id", "", DOC_ID_WELL_FORMED_RESOLUTION);
570
+ assertNfcSegment(id, "_id", "", DOC_ID_NFC_RESOLUTION);
571
+ };
572
+ /**
573
+ * Guard an `_id` that names an existing row: the `doc_id` of a delete.
574
+ * Only the key-segment rule applies (the single shared
575
+ * {@link assertPathSegment}: empty / `"/"` / `"."`|`".."` / C0-C1 control
576
+ * chars / leading `"_"` (ADR-003) / overlong, all as
577
+ * `BaerlyError{code:"InvalidConfig"}`), so a row stored under a non-NFC
578
+ * id, or an id with an unpaired surrogate, before {@link assertDocId}
579
+ * refused them can still be deleted.
580
+ */
581
+ const assertStoredDocId = (id) => {
582
+ assertPathSegment(id, "_id");
583
+ };
584
+ /**
585
+ * Guard the `id` of a point read (`Collection.get`, `GET
586
+ * /v1/c/:collection/:id`) before any I/O. Applies the stored-id rule
587
+ * ({@link assertStoredDocId}), not the NFC or well-formed write rules, so
588
+ * a row an earlier release stored under such an id stays readable. The error is marked
589
+ * caller-facing so HTTP returns its message with the 400.
590
+ *
591
+ * @throws BaerlyError code="InvalidConfig" — `id` is not a string or breaks
592
+ * the key-segment rule.
593
+ */
594
+ const assertReadDocId = (id) => {
595
+ let message;
596
+ if (typeof id !== "string") message = `get: _id must be a string, got ${typeof id}`;
597
+ else try {
598
+ assertPathSegment(id, "_id", "get");
599
+ } catch (error) {
600
+ if (!(error instanceof BaerlyError)) throw error;
601
+ message = error.message;
602
+ }
603
+ if (message !== void 0) throw markCallerFacing(new BaerlyError("InvalidConfig", message, { resolution: READ_ID_RESOLUTION }));
604
+ };
605
+ /**
606
+ * The `AlreadyExists` an insert throws when a live row holds `docId`.
607
+ * Shared by `runInsert`'s check read (`./query.ts`) and the writer's
608
+ * insert guard (`./writer.ts`), so a caller sees one error whichever
609
+ * side caught the collision. Not retriable; `err._id` is `docId`.
610
+ */
611
+ const insertAlreadyExists = (collection, docId) => new BaerlyError("AlreadyExists", `insert: _id ${JSON.stringify(docId)} already exists in collection ${JSON.stringify(collection)}`, {
612
+ resolution: CODE_RESOLUTIONS.AlreadyExists,
613
+ _id: docId
614
+ });
615
+ /**
616
+ * `true` when the stored live row `stored` is the row an insert of `body`
617
+ * would have written: structurally equal after the JSON round-trip the
618
+ * write path's encoder applies (key order ignored, `undefined` properties
619
+ * dropped). `body` is the insert's post-image `{ ...doc, _id }`; the
620
+ * stored row carries no other server-stamped field (log metadata lives on
621
+ * the `LogEntry`, not in `after`).
622
+ *
623
+ * Shared by `runInsert`'s check read and the writer's insert guard, so an
624
+ * SDK-minted insert replays on the same rule whichever side found the row.
625
+ */
626
+ const insertReplaysRow = (body, stored) => stored !== void 0 && jsonValueEqual(JSON.parse(JSON.stringify(body)), stored);
627
+ /**
628
+ * Count an SDK-minted insert answered as a replay of its stored row on
629
+ * `db.write.insert_replayed_total` (labelled by `collection`). A replay
630
+ * commits nothing and records no write metric, so without this counter it
631
+ * is invisible on the canonical line. Shared by `runInsert`'s check read
632
+ * and the writer's insert guard, the two places a replay is decided.
633
+ */
634
+ const recordInsertReplay = (collection) => {
635
+ getCurrentContext()?.recorder.counter("db.write.insert_replayed_total", 1, { collection });
636
+ };
637
+ // packages/server/src/capacity.ts
638
+ /**
639
+ * Growth refusal at the host's fold ceiling (main-10, rulings G3–G5, G7).
640
+ *
641
+ * The in-band fold can only rebuild a snapshot within the serving host's
642
+ * ceilings: `E` rows (`maxFoldRows`) and `C` bytes (`maxFoldBytes`, or
643
+ * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`). `compact()` folds the longest
644
+ * prefix of the tail that keeps the snapshot within `E` rows, so it stops
645
+ * at the first entry that would add a row to an `E`-row snapshot, and of
646
+ * that, the longest prefix of its pass that rebuilds within `C` bytes. Past
647
+ * a point no pass can fold, nothing folds, and every read pays one GET per
648
+ * pending tail entry.
649
+ * The write verbs call {@link capacityDecision} after their pre-commit read
650
+ * and before any commit, so a refused write commits nothing, and again
651
+ * inside each commit, before its `log/<seq>` create, whenever another
652
+ * write landed since that read, so concurrent growth writes that each
653
+ * passed cannot together pass the ceiling (G5-race).
654
+ *
655
+ * The decision is a pure function of the state that read already loaded
656
+ * (`current.json`, the snapshot rows, the pending tail) plus the planned
657
+ * writes. Nothing is persisted, so the refusal clears as soon as that
658
+ * state changes.
659
+ *
660
+ * An admitted write that leaves the collection within
661
+ * `CAPACITY_WARN_FRACTION` of that point carries a warning (G7), computed
662
+ * from the same state, so it too needs no persisted flag.
663
+ *
664
+ * Near the ceiling the verbs also drive the fold (G6): an accepted write
665
+ * that leaves the collection at its growth-refusal point forces its
666
+ * write tick, and a refused growth write whose room the pending tail
667
+ * would free dispatches one forced fold and refuses with
668
+ * `MaintenancePending` instead of `CapacityExceeded`.
669
+ */
670
+ /**
671
+ * The fold ceilings and pass size of the host serving this request,
672
+ * resolved as the write-tick runner resolves them
673
+ * ({@link resolveFoldCeilings}, absent profile ⇒ cf-free) so refusal and
674
+ * folding always agree.
675
+ */
676
+ const currentFoldCeilings = () => {
677
+ const maint = getCurrentContext()?.maintenance;
678
+ const profile = maint?.options?.profile;
679
+ return {
680
+ ...resolveFoldCeilings(profile, maint?.maxFoldBytes),
681
+ maxFoldEntriesPerPass: (profile ?? MAINTENANCE_PROFILE_CF_FREE).maxFoldEntriesPerPass
682
+ };
683
+ };
684
+ /**
685
+ * The refusal message names the state and the app-side remedy only. The
686
+ * host-side route (a larger maintenance profile) is an operator decision:
687
+ * it reaches operators through the `fold_deferred` log line and
688
+ * `graduation.md`, never the app-authoring surface, so an agent reading
689
+ * this error is not invited to retune a host setting.
690
+ */
691
+ const refuse = (message) => new BaerlyError("CapacityExceeded", message, { resolution: CODE_RESOLUTIONS.CapacityExceeded });
692
+ /**
693
+ * Growth (G3): an insert, or an update whose post-image encodes larger
694
+ * than the row's current body. An update with no known `before` counts as
695
+ * growth, which fails closed.
696
+ */
697
+ const isGrowth = (write) => {
698
+ if (write.op === "I") return true;
699
+ if (write.op === "D" || write.after === void 0) return false;
700
+ return write.before === void 0 || rowBytes(write.docId, write.after) > rowBytes(write.docId, write.before);
701
+ };
702
+ /**
703
+ * Backpressure for a refused growth write whose room the pending tail
704
+ * frees once it folds (G6). Like `CapacityExceeded`, it names the state
705
+ * and the app-side remedy only.
706
+ */
707
+ const maintenancePending = (collection) => new BaerlyError("MaintenancePending", `collection ${JSON.stringify(collection)} is waiting on maintenance: this write would grow it past what this host can fold until the pending changes fold, so it was refused and not committed (rows a batch committed before it are kept). Retry after 1s.`, {
708
+ resolution: CODE_RESOLUTIONS.MaintenancePending,
709
+ retryAfter: 1
710
+ });
711
+ /** Canonical-line field carrying {@link CapacityWarning.text}. */
712
+ const CAPACITY_WARNING_FIELD = "capacity_warning";
713
+ /**
714
+ * The warning for a projection peaking at `peakRows` / `peakBytes`, or
715
+ * `undefined` while both dimensions sit under `CAPACITY_WARN_FRACTION` of
716
+ * their limits. The more-used dimension is reported. The text names the
717
+ * state and the app-side remedy only, like the refusal it precedes.
718
+ */
719
+ const warningFor = (peakRows, peakBytes, maxRows, byteLimit) => {
720
+ const rowFraction = peakRows / maxRows;
721
+ const byteFraction = peakBytes / byteLimit;
722
+ const rows = rowFraction >= byteFraction;
723
+ const fraction = rows ? rowFraction : byteFraction;
724
+ if (!(fraction >= .9) || !Number.isFinite(fraction)) return;
725
+ const used = rows ? peakRows : peakBytes;
726
+ const limit = rows ? maxRows : byteLimit;
727
+ const percent = Math.floor(fraction * 100);
728
+ return {
729
+ dimension: rows ? "rows" : "bytes",
730
+ used,
731
+ limit,
732
+ text: `this collection is at ${percent}% of what this host can hold (${used} of ${limit} ${rows ? "rows" : "bytes"}); inserts and growing updates will be refused at the limit. Delete rows or shrink documents to make room, or export with baerly admin dump.`
733
+ };
734
+ };
735
+ /**
736
+ * Stamp `warning` on the request's canonical line (and so the log record)
737
+ * under {@link CAPACITY_WARNING_FIELD}. The HTTP router copies the same
738
+ * text onto the write response. A no-op without a request context, as for
739
+ * any field setter.
740
+ */
741
+ const noteCapacityWarning = (warning) => {
742
+ getCurrentContext()?.fields.set(CAPACITY_WARNING_FIELD, warning.text);
743
+ };
744
+ /**
745
+ * Decide whether `writes` must be refused on the host with `ceilings`.
746
+ *
747
+ * - **No progress** (G5): the stored snapshot is over `E` rows or `C`
748
+ * bytes, or the pending tail holds an entry the fold stops at (one that
749
+ * adds a row while the projected snapshot holds `E` rows), or
750
+ * `maxFoldEntriesPerPass` consecutive pending seqs whose folded snapshot
751
+ * each rebuilds past `C`, a run no fold pass can cross. Every write is
752
+ * refused, since anything appended behind that point never folds on this
753
+ * host. A write that would itself complete such a run is refused too.
754
+ * - **Growth** (an insert or a byte-growing update, G3): refused when the
755
+ * projected snapshot, at its peak over every prefix of the pending tail
756
+ * followed by the planned writes up to this one, would reach `E` rows or
757
+ * exceed `C - CAPACITY_BYTES_MARGIN` bytes (G4). The peak counts because
758
+ * a fold can land at any prefix. `foldFreesRoom` (G6) is set when the
759
+ * same writes would be admitted onto the snapshot the whole pending tail
760
+ * folds to, and the whole tail folds within `C`, so folds alone admit
761
+ * the writes.
762
+ * - Anything else (deletes, same-size and shrinking updates) commits, at
763
+ * `E` rows included: the fold drains them in place. `pressure` reports
764
+ * whether the commit forces its write tick (see `forcesTick` inside).
765
+ *
766
+ * A batch is decided whole, before its first row commits. The verbs
767
+ * re-run the decision at each commit over the entries that landed since
768
+ * (G5-race, `admitWrites` in `./query.ts`), for the writes not yet
769
+ * committed.
770
+ *
771
+ * @param head `current.json` as the pre-commit read saw it.
772
+ * @param base The snapshot rows that read loaded (`docId → body`).
773
+ * @param tail Every log entry that read folded on top of `base`, in order.
774
+ */
775
+ const capacityDecision = (args) => {
776
+ const { collection, head, base, tail, writes, ceilings } = args;
777
+ if (writes.length === 0) return {
778
+ refusal: void 0,
779
+ pressure: false
780
+ };
781
+ const { maxFoldRows: maxRows, maxFoldBytes: maxBytes } = ceilings;
782
+ const byteLimit = maxBytes - 64;
783
+ const noProgress = (why) => ({
784
+ refusal: refuse(`collection ${JSON.stringify(collection)} has outgrown this host (${why}): no fold can make progress here, so every write is refused and reads keep working. The collection needs a larger host or graduation; export it with baerly admin dump.`),
785
+ foldFreesRoom: false
786
+ });
787
+ if (!isFoldViable(head.snapshot_bytes, head.snapshot_rows, ceilings)) return noProgress(`${head.snapshot_rows} rows of ${maxRows}, ${head.snapshot_bytes} bytes of ${maxBytes}`);
788
+ const own = tail.filter((entry) => isOwnCollection(entry.collection, collection));
789
+ const projection = projectSnapshot(head, base, collection);
790
+ const pass = ceilings.maxFoldEntriesPerPass;
791
+ let overRun = 0;
792
+ for (const [i, entry] of tail.entries()) {
793
+ if (isOwnCollection(entry.collection, collection)) {
794
+ if (projection.addsRow(entry.op, entry.doc_id, entry.after) && !(projection.rows < maxRows)) return noProgress(`a pending insert cannot fold onto ${projection.rows} rows of ${maxRows}`);
795
+ projection.apply(entry.op, entry.doc_id, entry.after);
796
+ }
797
+ overRun = projection.bytesAt(head.log_seq_start + i + 1) <= maxBytes ? 0 : overRun + 1;
798
+ if (!(overRun < pass)) return noProgress(`${overRun} pending entries in a row each leave the snapshot past ${maxBytes} bytes`);
799
+ }
800
+ const tailLands = overRun === 0;
801
+ /**
802
+ * Whether an accepted batch forces its write tick (G6), given `p` with
803
+ * the tail and the writes applied. Only at the refusal point (one more
804
+ * inserted row, or one more byte of growth, would be refused), and then
805
+ * only when that fold is worth its full snapshot rebuild:
806
+ *
807
+ * - folding the pending tail frees room for growth (the snapshot it
808
+ * rebuilds to admits one more row and byte), or
809
+ * - the pending tail, these writes included, holds a full pass
810
+ * (`maxFoldEntriesPerPass`).
811
+ *
812
+ * Otherwise the runner's ratio trigger and entry floor apply as usual.
813
+ * The pass floor is the cheapest cadence that keeps the tail bounded at
814
+ * the ceiling: every pending entry costs each read one GET, and on
815
+ * Workers Free the ratio trigger alone would let a collection held at
816
+ * `E - 1` by same-size updates queue ~300 entries. One forced fold per
817
+ * pass also bounds the rebuild cost to one full snapshot per
818
+ * `maxFoldEntriesPerPass` writes, rather than one per write, and with it
819
+ * the snapshots each rebuild orphans: on cf-free that is under one
820
+ * orphan (20-entry pass) per hard-GC interval of 16 writes, against that
821
+ * slice's sweep budget of 10, so GC keeps up even though a forced fold
822
+ * is the tick's only phase.
823
+ */
824
+ const forcesTick = (p) => {
825
+ if (!(!(Math.max(p.peakRows, p.rows + 1) < maxRows) || !(p.peakBytes < byteLimit))) return false;
826
+ if (!tailLands) return false;
827
+ return p.rows + 1 < maxRows && p.bytes < byteLimit || tail.length + writes.length >= pass;
828
+ };
829
+ /**
830
+ * The first write `p` refuses, applying every write onto `p` from a
831
+ * state `overRun` seqs into a run over `C`: a growth write past the
832
+ * growth limit, or any write that would complete a wall of `pass` seqs
833
+ * over `C` (`stranded`), which it would itself sit behind.
834
+ */
835
+ const firstRefused = (p, run) => {
836
+ for (const [j, write] of writes.entries()) {
837
+ const growth = isGrowth(write);
838
+ p.apply(write.op, write.docId, write.after);
839
+ if (growth && (!(p.peakRows < maxRows) || !(p.peakBytes <= byteLimit))) return {
840
+ write,
841
+ stranded: false
842
+ };
843
+ run = p.bytesAt(head.log_seq_start + tail.length + j + 1) <= maxBytes ? 0 : run + 1;
844
+ if (!(run < pass)) return {
845
+ write,
846
+ stranded: true
847
+ };
848
+ }
849
+ };
850
+ const first = firstRefused(projection, overRun);
851
+ if (first === void 0) {
852
+ const warning = warningFor(projection.peakRows, projection.peakBytes, maxRows, byteLimit);
853
+ return {
854
+ refusal: void 0,
855
+ pressure: forcesTick(projection),
856
+ ...warning !== void 0 && { warning }
857
+ };
858
+ }
859
+ if (first.stranded) return {
860
+ refusal: refuse(`collection ${JSON.stringify(collection)} is waiting on changes this host cannot fold: the pending changes leave it past ${maxBytes} bytes, and this write would leave them stuck there for good, so it was refused and not committed (rows a batch committed before it are kept). A write that brings the collection back within ${maxBytes} bytes still commits; otherwise it needs a larger host or graduation.`),
861
+ foldFreesRoom: false
862
+ };
863
+ const refused = first.write;
864
+ const { peakRows, peakBytes } = projection;
865
+ const detail = !(peakRows < maxRows) ? `${peakRows} rows would reach the ${maxRows}-row ceiling` : `${peakBytes} bytes would pass the ${maxBytes}-byte ceiling`;
866
+ const refusal = refuse(`collection ${JSON.stringify(collection)} is full on this host: ${detail}, so this ${refused.op === "I" ? "insert" : "growing update"} was refused and not committed (rows a batch committed before it are kept). Deletes and same-size or shrinking updates still commit; delete or shrink rows to make room. If the collection must keep growing, it needs a larger host or graduation.`);
867
+ if (own.length === 0 || !tailLands) return {
868
+ refusal,
869
+ foldFreesRoom: false
870
+ };
871
+ const settled = projectSnapshot(head, base, collection);
872
+ for (const entry of own) settled.apply(entry.op, entry.doc_id, entry.after);
873
+ settled.settle(head.log_seq_start + tail.length);
874
+ return {
875
+ refusal,
876
+ foldFreesRoom: firstRefused(settled, 0) === void 0
877
+ };
878
+ };
879
+ // packages/server/src/query-eval.ts
880
+ /**
881
+ * In-memory query evaluation over a folded row map: the predicate
882
+ * filter, the counting pass, `order` with its bounded top-k, and the
883
+ * `limit` cut. `runReadRows`
884
+ * (`./query.ts`) calls these after the snapshot + log fold; they do no
885
+ * I/O.
886
+ */
887
+ /**
888
+ * The rows of `docs` that satisfy `wire`, in map order, built in one pass.
889
+ * With no predicate, every row.
890
+ */
891
+ const filterRows = (docs, wire) => {
892
+ if (wire === void 0) return Array.from(docs, ([docId, doc]) => ({
893
+ docId,
894
+ doc
895
+ }));
896
+ const matches = compileWire(wire);
897
+ const rows = [];
898
+ for (const [docId, doc] of docs) if (matches(doc)) rows.push({
899
+ docId,
900
+ doc
901
+ });
902
+ return rows;
903
+ };
904
+ /** How many rows of `docs` satisfy `wire`, without materialising them. */
905
+ const countMatches = (docs, wire) => {
906
+ if (wire === void 0) return docs.size;
907
+ const matches = compileWire(wire);
908
+ let count = 0;
909
+ for (const doc of docs.values()) if (matches(doc)) count++;
910
+ return count;
911
+ };
912
+ /**
913
+ * How many of `n` rows `limit` keeps: the length `rows.slice(0, limit)`
914
+ * would have. Both the row path (which truncates to it) and the count
915
+ * use it, so a count honours `limit` exactly as `all()` does, including
916
+ * a fractional or negative `limit` (`slice` truncates it, and counts a
917
+ * negative end from the back).
918
+ */
919
+ const limitedLength = (n, limit) => {
920
+ if (limit === void 0 || !(limit < n)) return n;
921
+ const end = Math.trunc(limit) || 0;
922
+ return end < 0 ? Math.max(n + end, 0) : end;
923
+ };
924
+ /**
925
+ * Compare two primitive order-key values under one direction, as
926
+ * {@link sortByOrderSpec} does: a missing value sorts low under `asc`
927
+ * and high under `desc`; otherwise `<`. {@link orderRows} calls it only
928
+ * once its pre-scan has ruled out objects and `null`.
929
+ */
930
+ const compareKey = (a, b, desc) => {
931
+ if (a === b) return 0;
932
+ if (a === void 0) return desc ? 1 : -1;
933
+ if (b === void 0) return desc ? -1 : 1;
934
+ const cmp = a < b ? -1 : 1;
935
+ return desc ? -cmp : cmp;
936
+ };
937
+ /**
938
+ * Stable multi-key sort built from an `OrderSpec`. Keys are taken in
939
+ * the spec's insertion order, which matches the caller's source-order
940
+ * expectation. `Array.prototype.sort` is stable on Node 26+ and Workerd.
941
+ *
942
+ * Top-level fields only (locked at `OrderSpec<T>`).
943
+ * Values are `DocumentValue` — string / number / boolean / object —
944
+ * but only the primitive types are sensibly orderable; comparing two
945
+ * objects falls through to "considered equal," which preserves the
946
+ * stable-sort order of the input.
947
+ */
948
+ const sortByOrderSpec = (rows, spec) => {
949
+ const entries = Object.entries(spec);
950
+ return rows.toSorted((a, b) => {
951
+ for (const [field, dir] of entries) {
952
+ const av = a.doc[field];
953
+ const bv = b.doc[field];
954
+ if (av === bv) continue;
955
+ if (av === void 0) return dir === "desc" ? 1 : -1;
956
+ if (bv === void 0) return dir === "desc" ? -1 : 1;
957
+ if (typeof av === "object" || typeof bv === "object") continue;
958
+ const cmp = av < bv ? -1 : 1;
959
+ return dir === "desc" ? -cmp : cmp;
960
+ }
961
+ return 0;
962
+ });
963
+ };
964
+ /**
965
+ * `sortByOrderSpec(rows, spec)` cut by `limit` as the row path cuts it,
966
+ * without sorting every row when `limit` is small.
967
+ *
968
+ * The bounded path runs when `limit` is an integer in
969
+ * `[1, QUERY_TOP_K_MAX]` below `rows.length` (PostgreSQL's bounded
970
+ * top-N heapsort for `ORDER BY … LIMIT` has the same shape). One O(n)
971
+ * pass checks that each order key holds a single primitive type (plus
972
+ * missing values), under which the comparator is a total preorder; a
973
+ * key holding objects, `null` or mixed types falls back to the full
974
+ * sort, whose comparator is not transitive there. The same pass
975
+ * compares adjacent rows:
976
+ *
977
+ * - No row orders before its predecessor: the input is already in
978
+ * order, so the first `limit` rows are the answer.
979
+ * - No row orders after its predecessor: the input is in reverse order,
980
+ * so the answer is read from the end, keeping tied rows in input
981
+ * order.
982
+ * - Otherwise a max-heap keeps the best `limit` rows under the
983
+ * comparator, ties broken by input index, which is the stable sort's
984
+ * order. The heap's result does not depend on the order rows are fed
985
+ * in, so it reads the input from the end when more compared adjacent
986
+ * pairs fall than rise (later rows ordering first), which keeps root
987
+ * replacements rare on nearly reversed input.
988
+ *
989
+ * The output is identical to `sortByOrderSpec(rows, spec).slice(0, limit)`.
990
+ */
991
+ const orderRows = (rows, spec, limit) => {
992
+ const n = rows.length;
993
+ if (limit === void 0 || !Number.isInteger(limit) || limit < 1 || limit > 64 || limit >= n) return sortByOrderSpec(rows, spec);
994
+ const fields = Object.keys(spec);
995
+ const desc = fields.map((field) => spec[field] === "desc");
996
+ const types = [];
997
+ let prev = [];
998
+ let cur = [];
999
+ let ascents = 0;
1000
+ let descents = 0;
1001
+ for (let i = 0; i < n; i++) {
1002
+ const doc = rows[i].doc;
1003
+ for (let j = 0; j < fields.length; j++) {
1004
+ const value = doc[fields[j]];
1005
+ if (value !== void 0) {
1006
+ const type = typeof value;
1007
+ if (type === "object" || types[j] !== void 0 && types[j] !== type) return sortByOrderSpec(rows, spec).slice(0, limit);
1008
+ types[j] = type;
1009
+ }
1010
+ cur[j] = value;
1011
+ }
1012
+ if (i > 0 && (i <= 64 || ascents === 0 || descents === 0)) {
1013
+ let cmp = 0;
1014
+ for (let j = 0; j < fields.length && cmp === 0; j++) cmp = compareKey(prev[j], cur[j], desc[j]);
1015
+ if (cmp < 0) ascents++;
1016
+ else if (cmp > 0) descents++;
1017
+ }
1018
+ const swap = prev;
1019
+ prev = cur;
1020
+ cur = swap;
1021
+ }
1022
+ if (descents === 0) return rows.slice(0, limit);
1023
+ const compareKeys = (a, b) => {
1024
+ const x = rows[a].doc;
1025
+ const y = rows[b].doc;
1026
+ let cmp = 0;
1027
+ for (let j = 0; j < fields.length && cmp === 0; j++) cmp = compareKey(x[fields[j]], y[fields[j]], desc[j]);
1028
+ return cmp;
1029
+ };
1030
+ if (ascents === 0) {
1031
+ const out = [];
1032
+ let end = n;
1033
+ while (out.length < limit) {
1034
+ let start = end - 1;
1035
+ while (start > 0 && compareKeys(start - 1, start) === 0) start--;
1036
+ for (let i = start; i < end && out.length < limit; i++) out.push(rows[i]);
1037
+ end = start;
1038
+ }
1039
+ return out;
1040
+ }
1041
+ const compare = (a, b) => compareKeys(a, b) || a - b;
1042
+ const heap = [];
1043
+ const siftDown = (pos) => {
1044
+ for (;;) {
1045
+ const left = 2 * pos + 1;
1046
+ if (left >= limit) return;
1047
+ const right = left + 1;
1048
+ const worst = right < limit && compare(heap[right], heap[left]) > 0 ? right : left;
1049
+ if (compare(heap[worst], heap[pos]) < 0) return;
1050
+ [heap[pos], heap[worst]] = [heap[worst], heap[pos]];
1051
+ pos = worst;
1052
+ }
1053
+ };
1054
+ const backward = descents > ascents;
1055
+ for (let x = 0; x < n; x++) {
1056
+ const i = backward ? n - 1 - x : x;
1057
+ if (heap.length < limit) {
1058
+ if (heap.push(i) === limit) for (let pos = (limit >> 1) - 1; pos >= 0; pos--) siftDown(pos);
1059
+ } else if (compare(i, heap[0]) < 0) {
1060
+ heap[0] = i;
1061
+ siftDown(0);
1062
+ }
1063
+ }
1064
+ return heap.toSorted(compare).map((i) => rows[i]);
1065
+ };
1066
+ // packages/server/src/read-admission.ts
1067
+ /**
1068
+ * Staged read admission (main-2): a read whose work falls outside the
1069
+ * serving host's read envelope is refused whole with `CapacityExceeded`,
1070
+ * never truncated, and a read inside it is served exactly as on any other
1071
+ * host (P1). Reads stay pure: a refusal writes nothing and dispatches no
1072
+ * maintenance, so a read never carries `MaintenancePending`.
1073
+ *
1074
+ * Every read, index-covered or not, is a full fold: it takes membership
1075
+ * from the snapshot plus the log tail, never from an index LIST, so its
1076
+ * work is bounded by the full-fold bounds below (I1: materialized =
1077
+ * snapshot rows + tail entries). There is no index-specific bound.
1078
+ *
1079
+ * Two stages, both over the current layout (one snapshot plus the live
1080
+ * log tail):
1081
+ *
1082
+ * 1. **Head.** `current.json` alone refuses a read that is certain not to
1083
+ * fit: its snapshot is over the byte or row bound, or the strict log
1084
+ * range `[log_seq_start, tail_hint)` alone is over the tail or
1085
+ * materialization bound, or the storage calls the read must issue at
1086
+ * least are more than the request ledger has left. `tail_hint` is a
1087
+ * lower bound on the tail, so every head check is a lower bound and
1088
+ * never refuses a read that fits.
1089
+ * 2. **Staged.** The read charges each log body before decoding it (tail
1090
+ * entries, tail bytes, materialized rows), and checks the answer's row
1091
+ * count before returning it. Two buckets with identical heads but different tails are told apart
1092
+ * here. Storage calls are charged by the request ledger at issue
1093
+ * (`retryStorageCall`), retries included.
1094
+ *
1095
+ * Memory: the adapter `GET` has already allocated a body when its length is
1096
+ * checked; the head's `snapshot_bytes` bounds the snapshot before its GET.
1097
+ * A bounded-read `Storage` seam is not needed while each log entry is one
1098
+ * small object.
1099
+ */
1100
+ /** The serving host's read envelope; unbounded outside a context that sets one. */
1101
+ const currentReadEnvelope = () => getCurrentContext()?.readEnvelope ?? {};
1102
+ /**
1103
+ * Storage calls the active invocation's request ledger still allows on
1104
+ * `pool`; `Infinity` without a ledger.
1105
+ */
1106
+ const remainingStorageCalls = (pool = "internal") => currentRequestLedger()?.remaining(pool) ?? 1e400;
1107
+ const refuseRead = (collection, bound, why, remedy) => new BaerlyError("CapacityExceeded", `this read of collection ${JSON.stringify(collection)} ${why}, more than one request can do on this host, so it was refused and returned no rows. ${remedy}`, {
1108
+ resolution: remedy,
1109
+ cause: { bound }
1110
+ });
1111
+ /** Only for the output bound: a narrower predicate or a limit shrinks the answer, not the load. */
1112
+ const NARROW = "Do not retry unchanged: narrow the predicate or add a limit.";
1113
+ const TAIL = "Retry once maintenance has absorbed the pending writes: later writes run it as they commit, and so does a scheduled runScheduledMaintenance call. Until then this read is refused.";
1114
+ const OUTGROWN = "Do not retry unchanged: delete or shrink rows, or export the collection with baerly admin dump.";
1115
+ const MATERIALIZED = "Delete or shrink rows, or retry once maintenance has absorbed the pending writes (later writes and scheduled runScheduledMaintenance calls run it). Otherwise export the collection with baerly admin dump.";
1116
+ /**
1117
+ * One read's admission state. Built after the read GETs `current.json`;
1118
+ * {@link admitHead} runs before any other storage call, and the other
1119
+ * methods as the read stages its work. A refusal is always
1120
+ * `CapacityExceeded`, not retriable, whose `resolution` is the remedy for
1121
+ * the bound it hit.
1122
+ */
1123
+ var ReadBudget = class {
1124
+ #collection;
1125
+ #envelope;
1126
+ #snapshotRows = 0;
1127
+ #tailEntries = 0;
1128
+ #tailBytes = 0;
1129
+ constructor(collection, envelope = currentReadEnvelope()) {
1130
+ this.#collection = collection;
1131
+ this.#envelope = envelope;
1132
+ }
1133
+ /** The pool the host's storage charges; see {@link ReadEnvelope.requestPool}. */
1134
+ get requestPool() {
1135
+ return this.#envelope.requestPool ?? "internal";
1136
+ }
1137
+ /**
1138
+ * Refuse from the head alone when the read cannot fit (stage 1). Every
1139
+ * read folds up front: it loads the snapshot and walks the strict log
1140
+ * range `[log_seq_start, tail_hint)`. Every figure here is a lower bound
1141
+ * on the read's work, because `tail_hint` never passes the true tail.
1142
+ *
1143
+ * @throws BaerlyError code="CapacityExceeded"
1144
+ */
1145
+ admitHead(head) {
1146
+ const strict = Math.max(0, head.tail_hint - head.log_seq_start);
1147
+ if (strict > (this.#envelope.maxTailEntries ?? 1e400)) throw this.#tailEntriesRefusal(strict);
1148
+ this.admitSnapshot(head, strict);
1149
+ const calls = 1 + strict + (head.snapshot === null ? 0 : 1);
1150
+ const left = remainingStorageCalls(this.requestPool);
1151
+ if (calls > left) throw refuseRead(this.#collection, "headStorageCalls", `must issue at least ${calls} storage calls, over the ${left} this request has left`, TAIL);
1152
+ }
1153
+ /**
1154
+ * Admit loading the snapshot `head` names, before its GET: its bytes and
1155
+ * rows, and its rows plus `pendingEntries` (the tail entries the read
1156
+ * will fold at least, beyond those already charged) toward
1157
+ * materialization.
1158
+ *
1159
+ * @throws BaerlyError code="CapacityExceeded"
1160
+ */
1161
+ admitSnapshot(head, pendingEntries = 0) {
1162
+ const env = this.#envelope;
1163
+ if (head.snapshot_bytes > (env.maxSnapshotBytes ?? 1e400)) throw refuseRead(this.#collection, "snapshotBytes", `must load a ${head.snapshot_bytes}-byte snapshot, over the ${env.maxSnapshotBytes} bytes it may load`, OUTGROWN);
1164
+ if (head.snapshot_rows > (env.maxSnapshotRows ?? 1e400)) throw refuseRead(this.#collection, "snapshotRows", `must decode ${head.snapshot_rows} snapshot rows, over the ${env.maxSnapshotRows} it may decode`, OUTGROWN);
1165
+ this.#snapshotRows = head.snapshot_rows;
1166
+ this.#checkMaterialized(this.#tailEntries + pendingEntries);
1167
+ }
1168
+ /**
1169
+ * Charge one log entry's stored body before it is decoded (stage 2).
1170
+ * Bound so it can be passed as a callback.
1171
+ *
1172
+ * @throws BaerlyError code="CapacityExceeded"
1173
+ */
1174
+ chargeTailBody = (bytes) => {
1175
+ const env = this.#envelope;
1176
+ this.#tailEntries += 1;
1177
+ this.#tailBytes += bytes;
1178
+ if (this.#tailEntries > (env.maxTailEntries ?? 1e400)) throw this.#tailEntriesRefusal(this.#tailEntries);
1179
+ if (this.#tailBytes > (env.maxTailBytes ?? 1e400)) throw refuseRead(this.#collection, "tailBytes", `must load more than ${env.maxTailBytes} bytes of pending log entries`, TAIL);
1180
+ this.#checkMaterialized(this.#tailEntries);
1181
+ };
1182
+ /**
1183
+ * The refusal for a forward probe that ran out of request budget before
1184
+ * it found the tail.
1185
+ */
1186
+ probeRefusal = () => refuseRead(this.#collection, "probeStorageCalls", `must probe more pending log entries than this request has storage calls left`, TAIL);
1187
+ /**
1188
+ * Refuse an answer over the output bound whole, never a truncated one.
1189
+ *
1190
+ * @throws BaerlyError code="CapacityExceeded"
1191
+ */
1192
+ admitOutput(rows) {
1193
+ const max = this.#envelope.maxOutputRows ?? 1e400;
1194
+ if (rows > max) throw refuseRead(this.#collection, "outputRows", `returns ${rows} rows, over the ${max} it may return`, NARROW);
1195
+ }
1196
+ #checkMaterialized(tailEntries) {
1197
+ const rows = this.#snapshotRows + tailEntries;
1198
+ const max = this.#envelope.maxMaterializedRows ?? 1e400;
1199
+ if (rows > max) throw refuseRead(this.#collection, "materializedRows", `must decode at least ${rows} rows before filtering, over the ${max} it may decode`, MATERIALIZED);
1200
+ }
1201
+ #tailEntriesRefusal(entries) {
1202
+ return refuseRead(this.#collection, "tailEntries", `must load at least ${entries} pending log entries, over the ${this.#envelope.maxTailEntries} it may load`, TAIL);
1203
+ }
1204
+ };
1205
+ // packages/server/src/schema.ts
1206
+ /**
1207
+ * Schema-validator runtime helper for `Db.insert` / `Query.update` /
1208
+ * `Collection.replace` boundary checks.
1209
+ *
1210
+ * The `SchemaValidator` / `SchemaIssue` TYPES live in
1211
+ * `@baerly/protocol` (cross-platform). This module owns the runtime
1212
+ * helper `validateOrThrow` that runs a validator and raises a
1213
+ * `BaerlyError{code:"SchemaError"}` on failure.
1214
+ *
1215
+ * @example
1216
+ * ```ts
1217
+ * import { z } from "zod";
1218
+ * import { defineConfig } from "@gusto/baerly-storage/config";
1219
+ *
1220
+ * const Ticket = z.object({
1221
+ * _id: z.string(),
1222
+ * status: z.enum(["open", "closed"]),
1223
+ * title: z.string().min(1),
1224
+ * });
1225
+ *
1226
+ * export default defineConfig({
1227
+ * collections: {
1228
+ * tickets: { schema: Ticket },
1229
+ * },
1230
+ * });
1231
+ * ```
1232
+ */
1233
+ /**
1234
+ * Run a validator and throw `BaerlyError{code:"SchemaError"}` on failure.
1235
+ * On success returns the validator's output (which for transforming
1236
+ * validators may differ from the input).
1237
+ *
1238
+ * Field paths are normalised to `(string | number)[]` so the wire shape
1239
+ * is JSON-clean. Symbol keys (rare; StandardSchemaV1 permits them) are
1240
+ * coerced to `String(sym)` — we never emit `symbol` on the wire.
1241
+ *
1242
+ * The thrown error's `message` carries a one-line summary
1243
+ * (`"<collection>.<verb>: <issuesCount> field(s) failed validation: <first>"`)
1244
+ * for stderr-readable logs; the structured `issues` are on `.issues`.
1245
+ */
1246
+ const validateOrThrow = async (schema, candidate, context) => {
1247
+ const result = await schema["~standard"].validate(candidate);
1248
+ if (result.issues === void 0) return result.value;
1249
+ const issues = result.issues.map((i) => ({
1250
+ path: (i.path ?? []).map((p) => {
1251
+ const raw = typeof p === "object" && p !== null && "key" in p ? p.key : p;
1252
+ return typeof raw === "number" ? raw : String(raw);
1253
+ }),
1254
+ message: i.message
1255
+ }));
1256
+ const first = issues[0];
1257
+ const summary = first === void 0 ? "schema validation failed (no issues reported)" : `${first.path.length === 0 ? "<root>" : first.path.join(".")}: ${first.message}`;
1258
+ throw new BaerlyError("SchemaError", `${context.collection}.${context.verb}: ${issues.length} field${issues.length === 1 ? "" : "s"} failed validation: ${summary}`, { issues });
1259
+ };
1260
+ // packages/server/src/key-limit.ts
1261
+ const utf8 = new TextEncoder();
1262
+ /**
1263
+ * Reject an assembled object key over the S3/R2 full-key ceiling
1264
+ * ({@link MAX_KEY_BYTES}) as `InvalidConfig`. Per-segment caps don't
1265
+ * bound the sum, and index values skip `assertPathSegment` entirely, so
1266
+ * this post-encoding check at the writer's PUT sites is their only
1267
+ * overflow guard. @see docs/spec/storage-compatibility.md
1268
+ */
1269
+ const assertKeyWithinLimit = (key) => {
1270
+ const bytes = utf8.encode(key).length;
1271
+ if (bytes > 1024) throw new BaerlyError("InvalidConfig", `object key exceeds ${MAX_KEY_BYTES} bytes (got ${bytes}): ${JSON.stringify(key.slice(0, 80))}…`);
1272
+ };
1273
+ // packages/server/src/log-conflict-adoption.ts
1274
+ /**
1275
+ * Decide whether the entry already at `/log/<seq>.json` is the
1276
+ * writer's own prior in-flight attempt and may be adopted. Pure
1277
+ * function; no I/O. The caller performs the GET (when the log PUT
1278
+ * surfaces 412) and passes the read-back body in `ctx.existing`.
1279
+ *
1280
+ * ## Correctness precondition
1281
+ *
1282
+ * A fresh `session` id is minted per `commit()` call, seq-stable
1283
+ * across that call's retries. Adoption compares the writer-minted
1284
+ * intent/body fields as well as session and seq: a dropped-ack retry
1285
+ * reuses the same attempted entry and adopts, while a same-session /
1286
+ * same-seq occupant carrying a different logical mutation is treated as
1287
+ * a conflict and skipped by the caller's forward-probe loop.
1288
+ *
1289
+ * @see {@link AdoptionDecision} for the return shape.
1290
+ * @see The soundness invariant in this module's header docstring.
1291
+ */
1292
+ const tryAdoptOwnSessionLogEntry = (ctx) => {
1293
+ if (ctx.existing.session !== ctx.self.session) return {
1294
+ adopt: false,
1295
+ reason: "foreign-session"
1296
+ };
1297
+ if (ctx.existing.seq !== ctx.self.seq) return {
1298
+ adopt: false,
1299
+ reason: "wrong-seq"
1300
+ };
1301
+ if (JSON.stringify(ctx.existing) !== JSON.stringify(ctx.self)) return {
1302
+ adopt: false,
1303
+ reason: "intent-mismatch"
1304
+ };
1305
+ return {
1306
+ adopt: true,
1307
+ entry: ctx.existing
1308
+ };
1309
+ };
1310
+ // packages/server/src/post-image-identity.ts
1311
+ const throwBaerlyError = (code, message, cause) => {
1312
+ throw new BaerlyError(code, `post-image: ${message}`, { cause });
1313
+ };
1314
+ /**
1315
+ * Assert that an insert/update post-image names the document it is stored
1316
+ * under: `after` is a plain object (prototype `Object.prototype` or `null`,
1317
+ * not an array) whose own enumerable data property `_id` is a string
1318
+ * `=== docId`.
1319
+ *
1320
+ * This checks identity only. It does not validate `docId` against the
1321
+ * `utf8-scalar-v1` domain, and it does not validate any other field of the
1322
+ * document. Callers that need the scalar domain call `assertSnapshotDocId`
1323
+ * first.
1324
+ *
1325
+ * `code` selects the failure polarity: `InvalidConfig` for caller input,
1326
+ * `InvalidResponse` for stored input. Failures go through `fail` when given,
1327
+ * so a codec keeps its own message prefix; otherwise this throws a
1328
+ * `BaerlyError` with `code`.
1329
+ */
1330
+ function assertPostImageIdentity(docId, after, code, fail = throwBaerlyError) {
1331
+ if (after === null || typeof after !== "object" || Array.isArray(after)) fail(code, "after must be a document object");
1332
+ const prototype = Object.getPrototypeOf(after);
1333
+ if (prototype !== Object.prototype && prototype !== null) fail(code, "after must be a plain object");
1334
+ const descriptor = Object.getOwnPropertyDescriptor(after, "_id");
1335
+ if (descriptor === void 0 || !descriptor.enumerable || !("value" in descriptor)) fail(code, "after._id must be an own enumerable data property");
1336
+ if (typeof descriptor.value !== "string" || descriptor.value !== docId) fail(code, "after._id must equal doc_id");
1337
+ }
1338
+ // packages/server/src/writer.ts
1339
+ /**
1340
+ * `Writer` — stateless multi-instance write engine (single-write commit).
1341
+ *
1342
+ * Each {@link Writer.commit} reads `current.json` FRESH (for
1343
+ * `log_seq_start` / `tail_hint` as a probe FLOOR — a lower bound, NOT a
1344
+ * CAS precondition), then **creates `log/<seq>` via `If-None-Match: "*"`.
1345
+ * That create IS the commit / linearization point.** The writer writes NOTHING to `current.json` on the commit
1346
+ * path; `tail_hint` advances outside ordinary commits via compaction
1347
+ * folds, write-tick refreshes, and explicit operator/import paths. The
1348
+ * commit model and its invariants are recorded in ADR-004
1349
+ * (`docs/adr/004-single-write-commit.md`). The
1350
+ * optional integrity walk is gated by
1351
+ * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off).
1352
+ *
1353
+ * No per-write cache: every commit re-reads + re-probes, so N stateless
1354
+ * instances contend at one place — the `If-None-Match` create of
1355
+ * `log/<seq>`. The loser gets a 412 and re-probes forward to the next
1356
+ * empty slot. A 412 from the writer's OWN session at the same seq is its
1357
+ * own lost-ack / crashed-but-durable commit → adopted (not retried), so
1358
+ * the write lands at EXACTLY `seq`, never duplicated.
1359
+ *
1360
+ * **First insert wins.** An `I` carrying {@link CommitInput.insertGuard}
1361
+ * reads the log window its caller's absence check could not see and
1362
+ * refuses to commit over a live row a peer's `I` put there
1363
+ * (`AlreadyExists`), so of concurrent inserts of one `doc_id` at most one
1364
+ * commits (exactly one, absent storage failures). See {@link InsertGuard}
1365
+ * and `docs/spec/sync-protocol.md` §"Insert: the first `I` wins".
1366
+ *
1367
+ * **Caller re-decisions.** A {@link CommitAdmission} re-runs the caller's
1368
+ * decision over the same window; its verdict may replace a `U`'s
1369
+ * post-image, which the write verbs use to re-apply an update to the
1370
+ * newest version of its row. See {@link CommitVerdict} and
1371
+ * `docs/spec/sync-protocol.md` §"Update and delete: decided on the newest
1372
+ * row version".
1373
+ *
1374
+ * **Crash safety.** The `log/<seq>` create is the commit's only write.
1375
+ * `LogEntry.after` is the authoritative post-image, so a crash before the
1376
+ * create leaves nothing of the commit on the bucket, and a crash after it
1377
+ * leaves a durable commit. The writer maintains no secondary objects:
1378
+ * declared indexes change no storage call (ADR-004 Q4, superseded in 0.7).
1379
+ *
1380
+ * **`LogEntry` shape.** Emitted entries follow the contract in
1381
+ * `packages/protocol/src/log.ts` (see {@link LogEntry}) and
1382
+ * `docs/spec/log-entry-shape.md`. The on-bucket key is
1383
+ * `log/<seq>.json` (the integer `seq` is the load-bearing
1384
+ * identifier; the `lsn` string is schema-only).
1385
+ *
1386
+ * @see docs/spec/sync-protocol.md for the protocol invariants this
1387
+ * loop preserves.
1388
+ * @see docs/spec/log-entry-shape.md for the per-field contract.
1389
+ */
1390
+ const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
1391
+ const APPLICATION_JSON = "application/json";
1392
+ /**
1393
+ * Stateless write engine for the multi-instance core.
1394
+ *
1395
+ * Construction is cheap and performs zero I/O — adapters build a
1396
+ * fresh `Writer` per request and discard it. All real work
1397
+ * happens in {@link commit}.
1398
+ *
1399
+ * @example
1400
+ * ```ts
1401
+ * import { Writer } from "@gusto/baerly-storage";
1402
+ * import { MemoryStorage } from "@gusto/baerly-storage";
1403
+ *
1404
+ * const writer = new Writer({
1405
+ * storage: new MemoryStorage(),
1406
+ * currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
1407
+ * });
1408
+ *
1409
+ * const result = await writer.commit({
1410
+ * op: "I",
1411
+ * collection: "tickets",
1412
+ * docId: "doc-1",
1413
+ * body: { _id: "doc-1", title: "hello" },
1414
+ * });
1415
+ * console.log(result.entry.seq);
1416
+ * ```
1417
+ */
1418
+ var Writer = class {
1419
+ #storage;
1420
+ #currentJsonKey;
1421
+ #verifyLogIntegrityOnCommit;
1422
+ constructor(opts) {
1423
+ this.#storage = opts.storage;
1424
+ this.#currentJsonKey = opts.currentJsonKey;
1425
+ this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
1426
+ }
1427
+ /**
1428
+ * Atomically commit one mutation. Reads `current.json` fresh (as a
1429
+ * probe FLOOR, not a CAS precondition), then creates `log/<seq>` via
1430
+ * `If-None-Match: "*"` — that create IS the commit (single-write
1431
+ * commit; no `current.json` CAS follows it).
1432
+ *
1433
+ * The hot-path cost under no contention is 3 GETs + 1 PUT, whatever
1434
+ * indexes the collection declares: the Step 1 `current.json` read,
1435
+ * `findLogTail`'s forward probe (one 404 GET when `tail_hint` is
1436
+ * accurate, `O(log gap)` GETs when it lags a fold interval), the
1437
+ * committing `log/<seq>` create, and the post-create `current.json`
1438
+ * re-read that rejects a create landing below the certified delete
1439
+ * floor (`#assertCommitAboveDeleteFloor`). A peer that won the slot
1440
+ * costs one occupant readback GET, the forward probe's GETs, and one
1441
+ * more create at the next slot.
1442
+ *
1443
+ * Idempotency: `LogEntry.after` carries the full post-image, and the
1444
+ * `log/<seq>` create uses `If-None-Match: "*"`, so two writers racing
1445
+ * the same tail cause
1446
+ * exactly one create to win; the loser reads back the occupant,
1447
+ * adopts its own lost-ack write or re-probes forward to the next
1448
+ * empty slot.
1449
+ *
1450
+ * **Uncertain commit fate.** If the committing create wins at a
1451
+ * `seq` the collection has already certified deleted — reachable when a
1452
+ * create PUT or a lost-ack retry straddles a fold plus a retirement pass —
1453
+ * the object it wrote is beneath every reader's floor. The commit then fails
1454
+ * with `AmbiguousCommit` rather than acknowledging a mutation no fresh
1455
+ * reader can see. The writer cannot tell whether an earlier attempt of its
1456
+ * own landed and was folded before retirement removed the slot, so the
1457
+ * mutation may or may not have been applied. The same uncertainty exists
1458
+ * when a rejected create cannot be resolved by reading its slot, including
1459
+ * rejections that follow a send of unknown outcome. The Writer never
1460
+ * resends a create at the same slot (the adapter already retried it); it
1461
+ * reads the slot back once instead. A missing readback does not prove that
1462
+ * an earlier send will not land. Exact own-entry readback is adopted; an
1463
+ * unresolved fate throws `AmbiguousCommit` with `err.retriable === false`.
1464
+ * Reconcile state before deliberately retrying: a new logical call can
1465
+ * duplicate work, including minting a second auto-ID document.
1466
+ *
1467
+ * @throws BaerlyError code="AmbiguousCommit" when the committing create
1468
+ * landed below `min(log_delete_floor, log_seq_start)`, or a possibly
1469
+ * durable create could not be resolved. The mutation's fate is unknown;
1470
+ * `err._id` is `input.docId`.
1471
+ * @throws BaerlyError code="Internal" when a log entry expected in
1472
+ * `[0, tail_hint)` is missing — a protocol-invariant violation
1473
+ * (compactor bug or stale `current.json`).
1474
+ * @throws BaerlyError code="InvalidResponse" when a log-entry body
1475
+ * isn't valid JSON.
1476
+ * @throws BaerlyError code="InvalidConfig" when `docId` breaks the
1477
+ * key-segment rule, when an `I` / `U` `docId` is not NFC, when an
1478
+ * `I` / `U` body is not a plain object whose own `_id` is the string
1479
+ * `docId`, when an `I` / `U` post-image encodes to more than
1480
+ * `MAX_DOCUMENT_BYTES`, or when `insertGuard` is set on a non-`I` op.
1481
+ * Checked before any I/O (an admission verdict's replacement
1482
+ * post-image is size-checked when it is returned).
1483
+ * @throws BaerlyError code="AlreadyExists" when `insertGuard` is set and
1484
+ * the log window `[absentBelowSeq, seq)` holds a live `I` / `U` for
1485
+ * this doc (unless `replayIdentical` is set and its `after` equals the
1486
+ * body, which returns that entry instead). Nothing was committed;
1487
+ * `err._id` is `input.docId`.
1488
+ * @throws BaerlyError code="WriteConflict" when `insertGuard` or
1489
+ * `admission` is set and part of its window was folded and retired (or
1490
+ * is longer than `LOG_FORWARD_PROBE_CAP`) before the writer could read
1491
+ * it. Nothing was committed; re-read and retry.
1492
+ * @throws BaerlyError code="CapacityExceeded" when the request ledger
1493
+ * cannot afford this commit's create and `COMMIT_RESOLUTION_RESERVE`,
1494
+ * checked before each create; or when the ledger refused the create
1495
+ * itself before any attempt was sent (`cause.notApplied`), or any
1496
+ * storage call before it. Nothing was committed.
1497
+ * @throws whatever `admission.check` throws (the write verbs throw
1498
+ * `CapacityExceeded` or `MaintenancePending`). Nothing was committed.
1499
+ *
1500
+ * **Window cost.** A commit with `insertGuard` or `admission` probes the
1501
+ * tail linearly from `max(windowFrom, log_seq_start)` with
1502
+ * `probeTailFrom` instead of galloping from
1503
+ * `max(log_seq_start, tail_hint)`. Uncontended, `windowFrom` is the
1504
+ * tail, so that is one 404 GET. Each entry a peer committed after the
1505
+ * caller's read costs one more GET, and if a fold moved `log_seq_start`
1506
+ * past `windowFrom`, each folded slot in between costs one GET too.
1507
+ *
1508
+ * **Implicit provisioning.** When `current.json` does not exist at
1509
+ * `currentJsonKey` (fresh bucket, fresh collection), the writer
1510
+ * auto-creates it with a zero-state manifest before the commit
1511
+ * lands. The cost is one extra Class A PUT on the very first
1512
+ * commit per collection; steady-state cost is unchanged. A peer
1513
+ * racing the same first-write loses cleanly on the create CAS
1514
+ * and re-reads to pick up the winner's manifest.
1515
+ */
1516
+ async commit(input) {
1517
+ if (input.op === "D") assertStoredDocId(input.docId);
1518
+ else assertDocId(input.docId);
1519
+ if (input.op !== "D") {
1520
+ assertPostImageIdentity(input.docId, input.body, "InvalidConfig");
1521
+ assertDocumentSize(input.body, "Writer");
1522
+ }
1523
+ if (input.insertGuard !== void 0) assertInsertGuardShape(input);
1524
+ if (input.admission !== void 0) assertAdmissionShape(input);
1525
+ const session = uuid().slice(0, 6);
1526
+ const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
1527
+ const success = await this.#singleAttemptCommit(input, session, logPrefix, "Writer");
1528
+ if (success.replayed) recordInsertReplay(input.collection);
1529
+ else this.#emitWriteMetrics(input.collection, success.classAOps);
1530
+ return {
1531
+ entry: success.entries[0],
1532
+ currentEtag: success.currentEtag
1533
+ };
1534
+ }
1535
+ /**
1536
+ * One full commit attempt — the body of {@link commit}. Reads
1537
+ * `current.json`, then forward-probes the tail and creates `log/<seq>`
1538
+ * once via `If-None-Match: "*"` — the numbered log create IS the commit
1539
+ * (single-write commit; no `current.json` CAS follows it). Returns the
1540
+ * success payload.
1541
+ *
1542
+ * Commits exactly one {@link CommitInput} — the numbered log create is
1543
+ * the single linearization point per call.
1544
+ *
1545
+ * A log-create 412 is disambiguated by session read-back: own session
1546
+ * / own seq ⇒ our crashed-or-lost-ack commit is already durable ⇒
1547
+ * adopt; foreign session ⇒ re-probe forward and create at the next
1548
+ * empty slot. Each slot gets one `Storage.put` and never a same-slot
1549
+ * resend, because the adapter already retried it. A definitive
1550
+ * `AccessDenied` / `InvalidConfig` propagates as-is. A 412 or an uncertain
1551
+ * failure resolves by one occupant readback, because adapters can hide
1552
+ * earlier sends. When the call reports every attempt refused unapplied
1553
+ * (`cause.notApplied`), the same readback runs because a throttle can hide
1554
+ * a lost race: a foreign occupant forward-probes, a slot read back as
1555
+ * empty or unreadable propagates the retriable `NetworkError`: the
1556
+ * adapter already guarantees no attempt applied or can still apply.
1557
+ * Unresolved creates throw non-retriable `AmbiguousCommit`; failures
1558
+ * before the create propagate.
1559
+ *
1560
+ * Crash safety: the create is the attempt's only write. A crash before
1561
+ * it leaves nothing; a crash after it is a durable, committed write at
1562
+ * `seq`, carrying its full post-image in `LogEntry.after`.
1563
+ */
1564
+ async #singleAttemptCommit(input, session, logPrefix, errorPrefix) {
1565
+ const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
1566
+ const current = read.json;
1567
+ const baseEtag = read.etag;
1568
+ if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.tail_hint);
1569
+ const guard = input.insertGuard;
1570
+ const admission = input.admission;
1571
+ const windowFrom = guard?.absentBelowSeq ?? admission?.fromSeq;
1572
+ const logSeqStart = logSeqStartOf(current);
1573
+ let commitWindow;
1574
+ let admissionForces = false;
1575
+ let body = input.body;
1576
+ const decide = async (window, tail) => {
1577
+ if (admission === void 0) return;
1578
+ const verdict = await admission.check(window, tail);
1579
+ admissionForces = verdict?.forceMaintenance === true;
1580
+ if (verdict?.body !== void 0) {
1581
+ if (input.op !== "U") throw new BaerlyError("InvalidConfig", `${errorPrefix}: an admission verdict may replace only a U post-image; got op ${JSON.stringify(input.op)}`);
1582
+ assertPostImageIdentity(input.docId, verdict.body, "InvalidConfig");
1583
+ assertDocumentSize(verdict.body, errorPrefix);
1584
+ body = verdict.body;
1585
+ }
1586
+ };
1587
+ let preCommitTail;
1588
+ if (windowFrom === void 0) {
1589
+ const probeFloor = Math.max(logSeqStart, current.tail_hint);
1590
+ preCommitTail = await findLogTail(this.#storage, logPrefix, probeFloor);
1591
+ } else {
1592
+ const folded = await this.#readFoldedWindow(logPrefix, windowFrom, logSeqStart, errorPrefix);
1593
+ const probe = await probeTailFrom(this.#storage, logPrefix, Math.max(windowFrom, logSeqStart));
1594
+ commitWindow = [...folded, ...probe.entries];
1595
+ if (guard !== void 0) {
1596
+ const replayed = decideInsertTarget(commitWindow, input);
1597
+ if (replayed !== void 0) return {
1598
+ replayed: true,
1599
+ entries: [replayed],
1600
+ currentEtag: baseEtag
1601
+ };
1602
+ }
1603
+ await decide(commitWindow, probe.tail);
1604
+ preCommitTail = probe.tail;
1605
+ }
1606
+ let seq = preCommitTail;
1607
+ const commitNowMs = Date.now();
1608
+ const commitTs = new Date(commitNowMs).toISOString();
1609
+ const lsnTimestamp = timestamp(commitNowMs);
1610
+ const mintEntry = (atSeq) => ({
1611
+ lsn: `${lsnTimestamp}_${session}_${countKey(atSeq)}`,
1612
+ commit_ts: commitTs,
1613
+ op: input.op,
1614
+ collection: input.collection,
1615
+ doc_id: input.docId,
1616
+ session,
1617
+ seq: atSeq,
1618
+ ...input.op !== "D" && body !== void 0 ? { after: body } : {},
1619
+ ...input.origin !== void 0 ? { origin: input.origin } : {}
1620
+ });
1621
+ let entry = mintEntry(seq);
1622
+ let committedEntry;
1623
+ let probes = 0;
1624
+ const ambiguous = (cause) => {
1625
+ ctxMetrics().counter("db.write.unresolved_create_total", 1, { collection: entry.collection });
1626
+ return new BaerlyError("AmbiguousCommit", `${errorPrefix}: the committing create at seq ${seq} on ${this.#currentJsonKey} was rejected and its fate could not be resolved; an earlier send may already have landed or may still land, so retrying may duplicate logical work`, {
1627
+ cause,
1628
+ resolution: CODE_RESOLUTIONS.AmbiguousCommit,
1629
+ _id: entry.doc_id
1630
+ });
1631
+ };
1632
+ for (;;) {
1633
+ const outcome = await this.#withCommitHold(errorPrefix, async () => {
1634
+ const logEntryKey = logObjectKey(logPrefix, seq);
1635
+ assertKeyWithinLimit(logEntryKey);
1636
+ const entryBody = encodeJsonBytes(entry);
1637
+ let resolved;
1638
+ let createFailure;
1639
+ let notApplied = false;
1640
+ try {
1641
+ await this.#storage.put(logEntryKey, entryBody, {
1642
+ ifNoneMatch: "*",
1643
+ contentType: APPLICATION_JSON
1644
+ });
1645
+ resolved = entry;
1646
+ } catch (error) {
1647
+ createFailure = error;
1648
+ this.#observe429(error, entry.collection);
1649
+ if (isWriteConflict(error)) ctxMetrics().counter("db.r2.put.412_total", 1, {
1650
+ collection: entry.collection,
1651
+ step: "log-put"
1652
+ });
1653
+ else if (isDefinitiveCreateRejection(error)) throw error;
1654
+ else if (isCreateNotApplied(error)) notApplied = true;
1655
+ }
1656
+ if (resolved === void 0) {
1657
+ let occupant;
1658
+ let decision;
1659
+ try {
1660
+ occupant = await this.#readLogOccupant(logEntryKey);
1661
+ decision = tryAdoptOwnSessionLogEntry({
1662
+ self: entry,
1663
+ existing: occupant
1664
+ });
1665
+ } catch (error) {
1666
+ if (notApplied) throw createFailure;
1667
+ throw ambiguous(new AggregateError([createFailure, error], "The create and its readback could not be resolved"));
1668
+ }
1669
+ if (!decision.adopt) return { foreign: occupant };
1670
+ resolved = decision.entry;
1671
+ }
1672
+ await this.#assertCommitAboveDeleteFloor(logPrefix, seq, input.collection, input.docId, errorPrefix);
1673
+ return { committed: resolved };
1674
+ });
1675
+ if ("committed" in outcome) {
1676
+ committedEntry = outcome.committed;
1677
+ break;
1678
+ }
1679
+ const occupant = outcome.foreign;
1680
+ if (++probes > 1e5) throw new BaerlyError("Internal", `${errorPrefix}: log-tail forward-probe exceeded ${LOG_FORWARD_PROBE_CAP} on ${this.#currentJsonKey}`);
1681
+ if (commitWindow === void 0) seq = await findLogTail(this.#storage, logPrefix, seq + 1);
1682
+ else {
1683
+ commitWindow.push(occupant);
1684
+ const probe = await probeTailFrom(this.#storage, logPrefix, seq + 1);
1685
+ commitWindow.push(...probe.entries);
1686
+ if (guard !== void 0) {
1687
+ const replayed = decideInsertTarget(commitWindow, input);
1688
+ if (replayed !== void 0) return {
1689
+ replayed: true,
1690
+ entries: [replayed],
1691
+ currentEtag: baseEtag
1692
+ };
1693
+ }
1694
+ await decide(commitWindow, probe.tail);
1695
+ seq = probe.tail;
1696
+ }
1697
+ entry = mintEntry(seq);
1698
+ }
1699
+ const committedEntries = [committedEntry];
1700
+ const prevSeq = preCommitTail;
1701
+ const observedTail = seq + 1;
1702
+ const maint = getCurrentContext()?.maintenance;
1703
+ const gcInterval = maint?.options?.profile?.gcInterval ?? MAINTENANCE_PROFILE_CF_FREE.gcInterval;
1704
+ const forceFold = (input.forceMaintenance === true || admissionForces) && maint?.disabled !== true;
1705
+ const foldAtTailEntries = (maint?.options)?.foldAtTailEntries;
1706
+ if (maint?.disabled === true ? observedTail - current.tail_hint >= 128 : forceFold || foldAtTailEntries !== void 0 && observedTail - current.log_seq_start >= foldAtTailEntries || shouldFireMaintenance(current, prevSeq, gcInterval, observedTail)) await dispatchWriteTick({
1707
+ storage: this.#storage,
1708
+ currentJsonKey: this.#currentJsonKey,
1709
+ collection: input.collection,
1710
+ prevSeq,
1711
+ observedTail,
1712
+ ...forceFold && { forceFold: true }
1713
+ });
1714
+ return {
1715
+ replayed: false,
1716
+ entries: committedEntries,
1717
+ currentEtag: baseEtag,
1718
+ classAOps: 1
1719
+ };
1720
+ }
1721
+ /**
1722
+ * Auto-create the per-collection `current.json` at
1723
+ * `this.#currentJsonKey` with a zero-state initial manifest. Called
1724
+ * by `#singleAttemptCommit` when the read returned `null` (fresh
1725
+ * bucket / fresh collection).
1726
+ *
1727
+ * Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
1728
+ * peer raced us and won, the storage layer surfaces `WriteConflict`; we
1729
+ * recover by re-reading the now-present manifest. We do NOT retry
1730
+ * the create — a single recover-via-read covers every race that
1731
+ * could have produced our null read.
1732
+ *
1733
+ * The seed shape (`snapshot: null`, `tail_hint: 0`, `log_seq_start:
1734
+ * 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
1735
+ * matches `ensureTable`, so an
1736
+ * operator who pre-provisions and a writer who auto-creates land on
1737
+ * equivalent state. NOT byte-identical any more: `generation` is a
1738
+ * fresh nonce per provisioner. That is harmless — `If-None-Match`
1739
+ * means exactly one of them ever lands, and no reader compares a
1740
+ * generation across provisioners, only against the cursor it minted.
1741
+ *
1742
+ * @throws BaerlyError code="InvalidResponse" — the post-recover
1743
+ * re-read also returned null. Defensive guard; in practice
1744
+ * unreachable because the WriteConflict implies the key now exists.
1745
+ */
1746
+ async #provisionCurrentJson() {
1747
+ const initial = {
1748
+ schema_version: 3,
1749
+ snapshot: null,
1750
+ tail_hint: 0,
1751
+ log_seq_start: 0,
1752
+ writer_fence: {
1753
+ epoch: 0,
1754
+ owner: "",
1755
+ claimed_at: ""
1756
+ },
1757
+ snapshot_bytes: 0,
1758
+ snapshot_rows: 0,
1759
+ generation: mintGeneration()
1760
+ };
1761
+ let createFailure;
1762
+ try {
1763
+ return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
1764
+ } catch (error) {
1765
+ if (!isWriteConflict(error) && !isCreateNotApplied(error)) throw error;
1766
+ createFailure = error;
1767
+ }
1768
+ const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
1769
+ if (recovered === null && isCreateNotApplied(createFailure)) throw createFailure;
1770
+ if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
1771
+ return recovered;
1772
+ }
1773
+ /**
1774
+ * Fail the commit if the create landed at a sequence the collection has
1775
+ * already certified deleted.
1776
+ *
1777
+ * **What a sub-floor `seq` proves, and what it does not.** A winning
1778
+ * `If-None-Match: "*"` create means the slot was empty immediately before the
1779
+ * PUT, so the object this commit just wrote sits beneath every reader's floor
1780
+ * and no reader will ever consult it. What a sub-floor `seq` does NOT prove
1781
+ * is that the *logical mutation* is invisible. Two histories reach this
1782
+ * branch: the create re-filled a hole retirement had already certified
1783
+ * deleted (invisible — the defect this check exists for), or it landed in a
1784
+ * live empty slot that a fold and then a retirement pass swept out from under
1785
+ * it (visible through the snapshot). That second history is a real
1786
+ * over-rejection, pinned as contract by a test in
1787
+ * `./log-retirement-aba.test.ts`, not an accident. It is the safe direction,
1788
+ * and "What the caller is being told" below is why guessing between the two
1789
+ * is worse than reporting both as ambiguous.
1790
+ *
1791
+ * **`log_delete_floor <= seq < log_seq_start` is NOT a failure.** Not because
1792
+ * that band is provably safe — it is undecidable in the very same way. A
1793
+ * winning create means the slot was empty just before the PUT, so what a fold
1794
+ * absorbed there was either an earlier attempt of ours (mutation visible) or
1795
+ * a foreign writer's entry (ours invisible), and the fold keeps no writer
1796
+ * identity to tell them apart. The band is accepted because keying the check
1797
+ * on `log_seq_start` would reject ordinary post-fold commits — a far
1798
+ * larger harm than the residual it would catch. That residual is the
1799
+ * invisible half of the undecidable band `docs/spec/sync-protocol.md`
1800
+ * invariant 5 describes; it is not reachable by the certified-floor check,
1801
+ * by construction.
1802
+ *
1803
+ * The floor is clamped to `min(log_delete_floor, log_seq_start)` for the
1804
+ * reason invariant 12 gives: the `<= log_seq_start` bound is
1805
+ * transition-scoped, so an out-of-bound stored floor is readable off disk
1806
+ * and would otherwise fail a perfectly good commit.
1807
+ *
1808
+ * **What the caller is being told.** Not "your write failed" —
1809
+ * `AmbiguousCommit`. An earlier attempt by this same writer may have landed
1810
+ * and been folded before retirement removed the slot, and nothing durable
1811
+ * distinguishes that history from a foreign writer's entry being folded
1812
+ * instead: the fold keeps no writer identity, tombstones are purged,
1813
+ * `current.json` holds no per-writer completion state, and `writer_fence` is
1814
+ * not a replay filter (invariant 11). So the write contract under this fault
1815
+ * is at-least-once, and re-probing-and-re-applying is emphatically not a
1816
+ * safe default: `LogEntry.after` is a full post-image, so a duplicate
1817
+ * clobbers a concurrent newer value and mints a second `lsn` for one logical
1818
+ * mutation.
1819
+ *
1820
+ * The phantom object is DELETEd best-effort, and it is the only thing
1821
+ * standing between a rejected commit and a permanently leaked object.
1822
+ * Nothing reclaims the phantom afterwards: it sits at a seq *below*
1823
+ * `log_delete_floor` — that is the precondition for reaching this branch —
1824
+ * and `computeRetirableRange` (`./log-retention.ts`) *starts* at the
1825
+ * certified floor, so retirement never revisits a slot beneath its own
1826
+ * floor. GC does not reclaim log objects at all. So a `cleanup: "failed"`
1827
+ * on `db.write.ambiguous_commit_total` is a genuine permanent leak, not a
1828
+ * deferral. Deleting it is safe: no reader may read below the certified
1829
+ * floor (invariant 5). A failed cleanup is recorded on the counter and never masks the
1830
+ * throw.
1831
+ *
1832
+ * **A failed manifest read skips the check rather than failing the commit —
1833
+ * except an abort, which propagates.** The check runs over an already-durable
1834
+ * create, and an unreadable manifest is no evidence of a sub-floor `seq`, so a
1835
+ * transient read failure is swallowed. An `AbortError` is rethrown instead: it
1836
+ * is the caller's own cancellation rather than a blip, and it carries none of
1837
+ * the `retriable` re-run hazard that motivates swallowing the rest. The skip
1838
+ * is recorded on `db.write.delete_floor_check_skipped_total` so a sustained
1839
+ * rate is visible to an operator rather than silent.
1840
+ *
1841
+ * Cost: one Class B GET per commit.
1842
+ * `billableClassAOps = puts + lists` excludes GET, so billing is unchanged;
1843
+ * it is one of the calls `COMMIT_RESOLUTION_RESERVE` keeps on the request
1844
+ * ledger.
1845
+ *
1846
+ * @throws BaerlyError code="AmbiguousCommit"
1847
+ */
1848
+ async #assertCommitAboveDeleteFloor(logPrefix, seq, collection, docId, errorPrefix) {
1849
+ let read;
1850
+ try {
1851
+ read = await readCurrentJson(this.#storage, this.#currentJsonKey);
1852
+ } catch (error) {
1853
+ if (isAbortError(error)) throw error;
1854
+ ctxMetrics().counter("db.write.delete_floor_check_skipped_total", 1, { collection });
1855
+ countPostCommitRefusal(error, collection, "delete-floor-check");
1856
+ return;
1857
+ }
1858
+ if (read === null) return;
1859
+ const deleteFloor = certifiedDeleteFloor(read.json);
1860
+ if (deleteFloor <= 0 || seq >= deleteFloor) return;
1861
+ let cleanup = "deleted";
1862
+ await this.#storage.delete(logObjectKey(logPrefix, seq)).catch(() => {
1863
+ cleanup = "failed";
1864
+ });
1865
+ ctxMetrics().counter("db.write.ambiguous_commit_total", 1, {
1866
+ collection,
1867
+ cleanup
1868
+ });
1869
+ throw new BaerlyError("AmbiguousCommit", `${errorPrefix}: the committing create at seq ${seq} on ${this.#currentJsonKey} landed below the certified delete floor ${deleteFloor}; that log object is beneath every reader's floor, and this mutation may or may not have been applied by an earlier attempt — retry is at-least-once`, {
1870
+ resolution: CODE_RESOLUTIONS.AmbiguousCommit,
1871
+ _id: docId
1872
+ });
1873
+ }
1874
+ /**
1875
+ * Run one commit slot's attempt, `fn` (the committing create and the
1876
+ * calls that resolve it), under a hold on the active request ledger of
1877
+ * everything it may spend: the create at full retries, plus
1878
+ * {@link COMMIT_RESOLUTION_RESERVE} for the readback and the delete-floor
1879
+ * check. `fn` runs in a child observability context carrying the hold, so
1880
+ * only its own storage calls draw on it; work outside that context (a
1881
+ * `ctx.waitUntil` write tick of an earlier row, the read cache) sees the
1882
+ * ledger net of it and cannot spend it. The hold is released when `fn`
1883
+ * settles.
1884
+ *
1885
+ * Refuses, before `fn` sends anything, when the ledger's room is short
1886
+ * of the hold. No create of this commit has landed or can land then:
1887
+ * before the first slot nothing was sent, and before a later one a
1888
+ * foreign occupant holds the slot this commit's only send targeted. A host without request
1889
+ * limits (Node, or no ledger) never refuses and takes no hold.
1890
+ *
1891
+ * @throws BaerlyError code="CapacityExceeded", cause `{ refused: true }`.
1892
+ */
1893
+ /**
1894
+ * The collection segment of `current.json`'s key, for messages that
1895
+ * reach HTTP callers unscrubbed (`CapacityExceeded` is `public`), which
1896
+ * must not carry the storage key.
1897
+ */
1898
+ #collectionName() {
1899
+ const parts = this.#currentJsonKey.split("/");
1900
+ return parts[parts.length - 2] ?? "";
1901
+ }
1902
+ async #withCommitHold(errorPrefix, fn) {
1903
+ const ctx = getCurrentContext();
1904
+ const ledger = ctx?.ledger;
1905
+ const remaining = ledger?.storageRemaining() ?? 1e400;
1906
+ if (ctx === void 0 || ledger === void 0 || remaining === 1e400) return await fn();
1907
+ const needed = 9;
1908
+ if (remaining < needed) throw new BaerlyError("CapacityExceeded", `${errorPrefix}: this request has ${String(remaining)} storage calls left, fewer than the ${String(needed)} a commit to collection ${JSON.stringify(this.#collectionName())} may need (the committing create, with retries, plus resolving it), so nothing was committed; the work this request needs does not fit in one request on this host`, { cause: {
1909
+ refused: true,
1910
+ needed,
1911
+ remaining
1912
+ } });
1913
+ const hold = ledger.hold(needed);
1914
+ try {
1915
+ return await runWithContext({
1916
+ ...ctx,
1917
+ hold
1918
+ }, fn);
1919
+ } finally {
1920
+ hold.release();
1921
+ }
1922
+ }
1923
+ /**
1924
+ * Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with
1925
+ * bounded parallelism via `walkLogRange`. Materialised entries are
1926
+ * discarded — the walk's only job is to surface a hole or a
1927
+ * malformed body inside the visible range as
1928
+ * `BaerlyError{code:"Internal"}` / `"InvalidResponse"`.
1929
+ *
1930
+ * Gated on `verifyLogIntegrityOnCommit`; default off in production
1931
+ * because the per-doc fold already lives in the read path. See the
1932
+ * option's docstring for the rationale and the opt-in convention.
1933
+ *
1934
+ * `logSeqStart` is the boundary set by the compactor on
1935
+ * `current.json.log_seq_start`. Entries below it have been folded
1936
+ * into the snapshot and may have been swept off the bucket, so the
1937
+ * walk MUST NOT GET-require them.
1938
+ */
1939
+ async #walkLog(logPrefix, logSeqStart, nextSeq) {
1940
+ await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);
1941
+ }
1942
+ /**
1943
+ * Read `[fromSeq, logSeqStart)` for a windowed commit (insert guard or
1944
+ * admission) whose window starts below the floor of this commit's
1945
+ * manifest read: a fold absorbed those entries after the caller's read. Slots below the floor stay
1946
+ * readable until log retirement deletes them, so a missing slot means
1947
+ * this commit can no longer check its window: `WriteConflict`, nothing
1948
+ * committed, and the caller's next read sees the folded state. A window
1949
+ * longer than {@link LOG_FORWARD_PROBE_CAP} is refused the same way
1950
+ * rather than spending an unbounded run of GETs on the write path.
1951
+ *
1952
+ * @throws BaerlyError code="WriteConflict" — a slot is missing, or the
1953
+ * range exceeds the cap.
1954
+ * @throws BaerlyError code="InvalidResponse" — a slot's body is not JSON.
1955
+ */
1956
+ async #readFoldedWindow(logPrefix, fromSeq, logSeqStart, errorPrefix) {
1957
+ if (fromSeq >= logSeqStart) return [];
1958
+ const refuse = (detail) => new BaerlyError("WriteConflict", `${errorPrefix}: commit window [${fromSeq}, ${logSeqStart}) on ${this.#currentJsonKey} ${detail}; nothing was committed`);
1959
+ if (logSeqStart - fromSeq > 1e5) throw refuse(`exceeds ${LOG_FORWARD_PROBE_CAP} folded entries`);
1960
+ const entries = [];
1961
+ for (let chunk = fromSeq; chunk < logSeqStart; chunk += 16) {
1962
+ const end = Math.min(chunk + 16, logSeqStart);
1963
+ const keys = Array.from({ length: end - chunk }, (_, i) => logObjectKey(logPrefix, chunk + i));
1964
+ const bodies = await Promise.all(keys.map((key) => this.#storage.get(key)));
1965
+ for (let i = 0; i < bodies.length; i++) {
1966
+ const got = bodies[i];
1967
+ if (got === null || got === void 0) throw refuse(`was retired at seq ${chunk + i} before it could be checked`);
1968
+ try {
1969
+ entries.push(decodeJsonBytes(got.body));
1970
+ } catch (error) {
1971
+ throw new BaerlyError("InvalidResponse", `${errorPrefix}: malformed log entry at ${keys[i]}`, { cause: error });
1972
+ }
1973
+ }
1974
+ }
1975
+ return entries;
1976
+ }
1977
+ /**
1978
+ * Read the occupant of a slot whose committing create was rejected, with
1979
+ * one `Storage.get` (the adapter retries it; the Writer does not). A failed
1980
+ * read, an empty slot, or an occupant without a writer identity throws:
1981
+ * none of them proves the slot holds a foreign entry rather than a pending
1982
+ * send of our own.
1983
+ */
1984
+ async #readLogOccupant(key) {
1985
+ const got = await this.#storage.get(key);
1986
+ if (got === null) throw new BaerlyError("NotFound", `Writer: ${key} is empty after its create was rejected`);
1987
+ let existing;
1988
+ try {
1989
+ existing = decodeJsonBytes(got.body);
1990
+ } catch (error) {
1991
+ throw new BaerlyError("InvalidResponse", `Writer: malformed log occupant at ${key}`, { cause: error });
1992
+ }
1993
+ if (!hasWriterIdentity(existing)) throw new BaerlyError("InvalidResponse", `Writer: malformed log occupant at ${key}`);
1994
+ return existing;
1995
+ }
1996
+ /**
1997
+ * Bump the `db.r2.put.429_total` counter when `err` looks like an
1998
+ * R2 prefix-partition rate-limit. Best-effort: detected via
1999
+ * `BaerlyError{code:"NetworkError"}` with a `429` token in the
2000
+ * message. Called from every PUT call site's catch arm; mutually
2001
+ * exclusive in practice with `isWriteConflict` (412 ≠ 429).
2002
+ */
2003
+ #observe429(err, collection) {
2004
+ if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
2005
+ }
2006
+ /**
2007
+ * Emit the per-logical-write `class_a_ops_per_logical_write`
2008
+ * histogram for `commit`. `classAOps` is the committing create, computed
2009
+ * by `#singleAttemptCommit`.
2010
+ */
2011
+ #emitWriteMetrics(collection, classAOps) {
2012
+ ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
2013
+ }
2014
+ };
2015
+ /**
2016
+ * `true` when a create rejection proves the create did not land. Under the
2017
+ * `Storage.put` contract an adapter that retried internally reports such a
2018
+ * rejection as `NetworkError`, so these codes describe the only attempt.
2019
+ */
2020
+ const isDefinitiveCreateRejection = (err) => err instanceof BaerlyError && (err.code === "AccessDenied" || err.code === "InvalidConfig");
2021
+ /**
2022
+ * `true` when a create-only put reports, per the `Storage.put` contract,
2023
+ * that no attempt of the call was applied: a `NetworkError` after every
2024
+ * attempt was throttled or refused before issue, or the request ledger's
2025
+ * `CapacityExceeded` when it refused the call before any attempt of
2026
+ * unknown outcome. `cause.notApplied` is the proof either way.
2027
+ */
2028
+ const isCreateNotApplied = (err) => err instanceof BaerlyError && (err.code === "NetworkError" || err.code === "CapacityExceeded") && err.cause?.notApplied === true;
2029
+ /**
2030
+ * Count a post-commit step the request ledger refused on
2031
+ * `db.write.post_commit_refused_total`. The step runs after a known
2032
+ * commit and swallows its failure, so the refusal leaves the commit
2033
+ * acknowledged; `phase` names the step that went without (the delete-floor
2034
+ * check is the only one).
2035
+ */
2036
+ const countPostCommitRefusal = (err, collection, phase) => {
2037
+ if (err instanceof BaerlyError && err.code === "CapacityExceeded" && err.cause?.refused === true) ctxMetrics().counter("db.write.post_commit_refused_total", 1, {
2038
+ collection,
2039
+ phase
2040
+ });
2041
+ };
2042
+ /**
2043
+ * Reject an `insertGuard` on anything but an `I`, or with an
2044
+ * `absentBelowSeq` that is not a log seq. Runs before any I/O.
2045
+ */
2046
+ const assertInsertGuardShape = (input) => {
2047
+ if (input.op !== "I") throw new BaerlyError("InvalidConfig", `Writer: insertGuard is valid only with op "I"; got op ${JSON.stringify(input.op)}`);
2048
+ const seq = input.insertGuard?.absentBelowSeq;
2049
+ if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0) throw new BaerlyError("InvalidConfig", `Writer: insertGuard.absentBelowSeq must be a non-negative safe integer; got ${String(seq)}`);
2050
+ const replay = input.insertGuard?.replayIdentical;
2051
+ if (replay !== void 0 && typeof replay !== "boolean") throw new BaerlyError("InvalidConfig", `Writer: insertGuard.replayIdentical must be a boolean; got ${typeof replay}`);
2052
+ };
2053
+ /**
2054
+ * Reject an `admission` whose `fromSeq` is not a log seq, or differs from
2055
+ * the insert guard's window start. Runs before any I/O.
2056
+ */
2057
+ const assertAdmissionShape = (input) => {
2058
+ const seq = input.admission?.fromSeq;
2059
+ if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0) throw new BaerlyError("InvalidConfig", `Writer: admission.fromSeq must be a non-negative safe integer; got ${String(seq)}`);
2060
+ if (typeof input.admission?.check !== "function") throw new BaerlyError("InvalidConfig", "Writer: admission.check must be a function");
2061
+ const guarded = input.insertGuard?.absentBelowSeq;
2062
+ if (guarded !== void 0 && guarded !== seq) throw new BaerlyError("InvalidConfig", `Writer: admission.fromSeq ${seq} must equal insertGuard.absentBelowSeq ${guarded}`);
2063
+ };
2064
+ /**
2065
+ * Window decision for a guarded insert. `window` holds the log entries
2066
+ * in `[absentBelowSeq, seq)` in seq order, unfiltered. The LAST entry for
2067
+ * this `(collection, doc_id)` decides: a `D`, or no entry, means the row
2068
+ * is absent and the insert may commit (`undefined`). An `I` or `U` means a
2069
+ * row is live: with `replayIdentical` set and that entry's `after` equal
2070
+ * to the body, the insert is a replay of its own earlier success and the
2071
+ * entry is returned; otherwise the insert throws `AlreadyExists`.
2072
+ *
2073
+ * @throws BaerlyError code="AlreadyExists"
2074
+ */
2075
+ const decideInsertTarget = (window, input) => {
2076
+ for (let i = window.length - 1; i >= 0; i--) {
2077
+ const e = window[i];
2078
+ if (!isOwnCollection(e.collection, input.collection) || e.doc_id !== input.docId) continue;
2079
+ if (e.op === "D") return;
2080
+ if (input.insertGuard?.replayIdentical === true && input.body !== void 0 && insertReplaysRow(input.body, e.after)) return e;
2081
+ throw insertAlreadyExists(input.collection, input.docId);
2082
+ }
2083
+ };
2084
+ /** `true` when a decoded log occupant carries the identity adoption compares. */
2085
+ const hasWriterIdentity = (value) => {
2086
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
2087
+ const { session, seq } = value;
2088
+ return typeof session === "string" && session.length > 0 && typeof seq === "number" && Number.isSafeInteger(seq) && seq >= 0;
2089
+ };
2090
+ /**
2091
+ * `true` when a rejection is an `AbortError` — the caller's own cancellation
2092
+ * through an `AbortSignal`, never a transient storage failure. Matched
2093
+ * structurally on `name` rather than `instanceof DOMException` because a host
2094
+ * may surface an abort as a plain `Error` so named (as `Storage` impls and the
2095
+ * test fixtures do). `@baerly/client` carries the same predicate; it is
2096
+ * duplicated rather than shared because `server` may not import `client`
2097
+ * (`scripts/lint-package-layers.mjs`) and one predicate does not earn a new
2098
+ * module in `@baerly/protocol`.
2099
+ */
2100
+ const isAbortError = (err) => typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
2101
+ /**
2102
+ * `true` when the underlying storage surfaced an R2 prefix-partition
2103
+ * rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
2104
+ * onto `BaerlyError.cause` as `{ status }`; we discriminate on that
2105
+ * structured field rather than regex-matching the message.
2106
+ */
2107
+ const is429 = (err) => {
2108
+ if (!(err instanceof BaerlyError) || err.code !== "NetworkError") return false;
2109
+ return err.cause?.status === 429;
2110
+ };
2111
+ // packages/server/src/query.ts
2112
+ /**
2113
+ * Read engine + mutation terminals: `Query<T>` builder, the
2114
+ * three read terminals (`first`, `all`, `count`) that fold the log
2115
+ * under a fresh `current.json` snapshot, and the four mutation
2116
+ * terminals (`insert`, `update`, `replace`, `delete`). Each mutation
2117
+ * verb compiles to exactly one `Writer.commit()` call.
2118
+ *
2119
+ * Every modifier (`.where` / `.order` / `.limit`) returns a NEW
2120
+ * `Query<T>` carrying merged frozen state — the input state is never
2121
+ * mutated. Identity inequality between the original and the returned
2122
+ * builder is intentional: callers cannot share a chain.
2123
+ *
2124
+ * `.where()` AND-merges through `mergePredicateWires` (clause-level
2125
+ * AND on the normalised wire form).
2126
+ * `.order()` and `.limit()` are last-call-wins (state replace).
2127
+ *
2128
+ * Each terminal reads `current.json` FRESH, loads the snapshot it names,
2129
+ * and walks `[log_seq_start, tail_hint)` directly — no cache, no
2130
+ * `list()` round-trip for the log. Per the multi-instance rules, every
2131
+ * read sees a fresh CAS snapshot.
2132
+ *
2133
+ * Mutation terminals are SINGLE-ATTEMPT per call site. Contention on the
2134
+ * committing log create is resolved inside `Writer.commit()` (occupant
2135
+ * readback, then a bounded forward probe); the verbs do NOT add their
2136
+ * own retry loop. Errors from `commit()` surface unchanged — the caller
2137
+ * decides whether to re-run.
2138
+ *
2139
+ * @see ../../../docs/spec/sync-protocol.md
2140
+ */
2141
+ const PATCH_ID_RESOLUTION = "Omit `_id` from the patch, or pass the row's own `_id`.";
2142
+ /**
2143
+ * Serialise a {@link CurrentJson} head into an opaque wire cursor.
2144
+ * `tail` is the DISCOVERED tail (defaults to `json.tail_hint` when no
2145
+ * probe has run). Physical snapshot keys feed the digest but never
2146
+ * cross the HTTP boundary.
2147
+ *
2148
+ * @internal — exported for `query.test.ts`.
2149
+ */
2150
+ const manifestPointerDigest = (seed) => {
2151
+ let hash = 14695981039346656037n;
2152
+ for (let i = 0; i < seed.length; i++) {
2153
+ hash ^= BigInt(seed.charCodeAt(i));
2154
+ hash = hash * 1099511628211n & 18446744073709551615n;
2155
+ }
2156
+ return hash.toString(36).padStart(13, "0");
2157
+ };
2158
+ const serializeManifestPointer = (json, tail = json.tail_hint) => `m1:${manifestPointerDigest([
2159
+ json.snapshot ?? "none",
2160
+ json.log_seq_start,
2161
+ json.tail_hint,
2162
+ json.snapshot_bytes,
2163
+ json.snapshot_rows,
2164
+ tail
2165
+ ].join("|"))}`;
2166
+ /**
2167
+ * Returns the id iff `wire` carries exactly one clause and that
2168
+ * clause is `{op:"eq", field:"_id", value:<string>}` — the shape
2169
+ * `runRead` short-circuits to a single `Map.get`. Any other shape
2170
+ * (multi-clause, non-`eq` op, non-`_id` field, non-string value)
2171
+ * returns `undefined` and falls through to the scan path.
2172
+ *
2173
+ * Kernel-internal `_id`-shaped wires (built by `byId`,
2174
+ * `runByIdWithMeta`, `runInsert`) bypass the wire validator by
2175
+ * design (`_id` at the root is a wire-only rejection); this
2176
+ * recogniser matches the same shape so the fast-path stays
2177
+ * symmetric.
2178
+ *
2179
+ * @internal
2180
+ */
2181
+ const singleIdFromPredicate = (wire) => {
2182
+ if (wire === void 0) return;
2183
+ if (wire.clauses.length !== 1) return;
2184
+ const clause = wire.clauses[0];
2185
+ if (clause.op !== "eq" || clause.field !== "_id") return;
2186
+ return typeof clause.value === "string" ? clause.value : void 0;
2187
+ };
2188
+ /**
2189
+ * Build a `Query<T>` from a context + frozen state. Every modifier
2190
+ * returns a NEW `Query<T>` carrying merged state — the input state
2191
+ * is never mutated. Identity inequality with the input chain is
2192
+ * intentional.
2193
+ *
2194
+ * Validation happens at the public seams — `Query.where(p)`
2195
+ * normalises + validates the incoming fragment before merging into
2196
+ * `state.wire`. By the time `makeQuery` is reached from elsewhere
2197
+ * (`Collection.where`, `runAllWithMeta`, kernel-internal `_id`-shaped
2198
+ * wires from `byId` / `runByIdWithMeta` / `runInsert`), the wire is
2199
+ * already trusted.
2200
+ *
2201
+ * @example
2202
+ * ```ts
2203
+ * const q = makeQuery<Ticket>(ctx, { wire: undefined, order: undefined, limit: undefined });
2204
+ * const open = await q.where({ status: "open" }).order({ created_at: "desc" }).limit(10).all();
2205
+ * ```
2206
+ *
2207
+ * @internal
2208
+ */
2209
+ const makeQuery = (ctx, state) => {
2210
+ return {
2211
+ where: (p) => {
2212
+ const incoming = normalizePredicateArg(p);
2213
+ validateWire(incoming);
2214
+ return makeQuery(ctx, {
2215
+ ...state,
2216
+ wire: state.wire === void 0 ? incoming : mergePredicateWires(state.wire, incoming)
2217
+ });
2218
+ },
2219
+ order: (s) => makeQuery(ctx, {
2220
+ ...state,
2221
+ order: s
2222
+ }),
2223
+ limit: (n) => makeQuery(ctx, {
2224
+ ...state,
2225
+ limit: n
2226
+ }),
2227
+ first: async () => {
2228
+ const { rows } = await runRead(ctx, {
2229
+ ...state,
2230
+ limit: 1
2231
+ });
2232
+ return rows[0];
2233
+ },
2234
+ all: async () => {
2235
+ return (await runRead(ctx, state)).rows;
2236
+ },
2237
+ count: async () => {
2238
+ return (await runRead(ctx, state, { countOnly: true })).count;
2239
+ },
2240
+ update: (patch) => runUpdate(ctx, state, patch),
2241
+ delete: () => runDelete(ctx, state)
2242
+ };
2243
+ };
2244
+ /**
2245
+ * Server-internal read entry surfacing the manifest-pointer cursor
2246
+ * and freshness flag alongside the materialised rows. The HTTP
2247
+ * router calls this directly so the read-response handler can pack
2248
+ * `_meta` onto the envelope; the public `Query<T>` terminals
2249
+ * destructure the rows out and discard the cursor to keep the
2250
+ * locked interface signature. Single-row routes (`GET /v1/c/:collection/:id`)
2251
+ * call this with `limit:1` and pick `rows[0]`.
2252
+ *
2253
+ * `state.wire` is assumed already validated — the public seam
2254
+ * (`Query.where(p)` → `normalizePredicateArg` → `validateWire`) is
2255
+ * the wire-arrival contract surface. Router callers parsing
2256
+ * `?where=` run `validateWire` themselves inside `parseWhereParam`,
2257
+ * keeping a single validation pass per wire.
2258
+ *
2259
+ * @internal
2260
+ */
2261
+ const runAllWithMeta = (ctx, state, opts) => {
2262
+ return runRead(ctx, state, opts);
2263
+ };
2264
+ /**
2265
+ * By-id read entry surfacing the same `ReadResult<T>` shape as
2266
+ * {@link runAllWithMeta} so the HTTP router can preserve the
2267
+ * `_meta` wire envelope while routing through the PK-lookup
2268
+ * fast-path. Mirrors {@link runAllWithMeta}'s signature; the
2269
+ * wire is built internally as a single-clause `{op:"eq",
2270
+ * field:"_id", value:id}` shape (same form as the `byId` helper in
2271
+ * `./collection.ts` and the `runInsert` duplicate-collision check)
2272
+ * which routes through `runRead`'s `singleIdFromPredicate`
2273
+ * short-circuit automatically.
2274
+ *
2275
+ * Bypasses {@link validateWire} — the wire is kernel-constructed,
2276
+ * never wire-submitted, so it would always pass the structural
2277
+ * rules. Skipping the validator also keeps this helper usable
2278
+ * from kernel-internal sites (`Collection<T>.get` etc.) without
2279
+ * tripping the wire-only rule that bans top-level `_id`.
2280
+ *
2281
+ * `id` is checked by {@link assertReadDocId} before any I/O.
2282
+ *
2283
+ * @internal — router uses this to preserve `_meta` envelope;
2284
+ * mirrors {@link runAllWithMeta} and {@link Collection.get}.
2285
+ */
2286
+ const runByIdWithMeta = async (ctx, id) => {
2287
+ assertReadDocId(id);
2288
+ return await runRead(ctx, {
2289
+ wire: { clauses: [{
2290
+ op: "eq",
2291
+ field: "_id",
2292
+ value: id
2293
+ }] },
2294
+ order: void 0,
2295
+ limit: 1
2296
+ });
2297
+ };
2298
+ /**
2299
+ * Build a fresh `Writer` bound to this collection's `current.json`.
2300
+ * Construction is zero-I/O (writer.ts:160) so we mint one per
2301
+ * `commit()` rather than caching on the chain; the writer holds no
2302
+ * per-commit state, so this costs nothing.
2303
+ */
2304
+ const writerFor = (ctx) => new Writer({
2305
+ storage: ctx.storage,
2306
+ currentJsonKey: `${ctx.collectionPrefix}/current.json`
2307
+ });
2308
+ /**
2309
+ * Throw the refusal `decision` carries: `MaintenancePending` when the
2310
+ * pending tail would make room once it folds, after dispatching one forced
2311
+ * fold pass (G6, fold-then-refuse) through the request's maintenance
2312
+ * dispatch, so on Cloudflare it runs in `ctx.waitUntil` like any write
2313
+ * tick; otherwise `CapacityExceeded`. Under `BAERLY_MAINTENANCE_DISABLE`
2314
+ * nothing can fold, so the refusal stays `CapacityExceeded`.
2315
+ *
2316
+ * @param tail The log tail the decision folded through.
2317
+ */
2318
+ const throwRefusal = async (ctx, decision, tail) => {
2319
+ if (decision.foldFreesRoom && getCurrentContext()?.maintenance?.disabled !== true) {
2320
+ await dispatchWriteTick({
2321
+ storage: ctx.storage,
2322
+ currentJsonKey: `${ctx.collectionPrefix}/current.json`,
2323
+ collection: ctx.collectionName,
2324
+ prevSeq: tail,
2325
+ observedTail: tail,
2326
+ forceFold: true
2327
+ });
2328
+ throw maintenancePending(ctx.collectionName);
2329
+ }
2330
+ throw decision.refusal;
2331
+ };
2332
+ /**
2333
+ * Thrown from an admission check when the row a planned `U` / `D` targets
2334
+ * was deleted after the verb's read, or no longer qualifies for it. The
2335
+ * writer propagates it before the committing create, so nothing commits;
2336
+ * the verb that planned the write catches it (`update` / `delete` leave the
2337
+ * row out of their count, `replace` throws `NotFound`). Never escapes
2338
+ * `query.ts`.
2339
+ */
2340
+ var RowSkipped = class extends Error {
2341
+ constructor(docId) {
2342
+ super(`row ${JSON.stringify(docId)} changed under the write`);
2343
+ this.name = "RowSkipped";
2344
+ }
2345
+ };
2346
+ /**
2347
+ * The newest version of `docId` among `entries` (every entry committed
2348
+ * after the verb's read, in seq order): `"gone"` when any of them deletes
2349
+ * it, its newest post-image when one rewrote it, `undefined` when none
2350
+ * touched it.
2351
+ */
2352
+ const newestVersion = (entries, collection, docId) => {
2353
+ let newest;
2354
+ for (const entry of entries) {
2355
+ if (!isOwnCollection(entry.collection, collection) || entry.doc_id !== docId) continue;
2356
+ if (entry.op === "D" || entry.after === void 0) return "gone";
2357
+ newest = entry.after;
2358
+ }
2359
+ return newest;
2360
+ };
2361
+ /** A never-provisioned collection: no snapshot, nothing folded. */
2362
+ const EMPTY_HEAD = {
2363
+ snapshot_rows: 0,
2364
+ snapshot_bytes: 0,
2365
+ log_seq_start: 0
2366
+ };
2367
+ /**
2368
+ * Admit `writes` against the serving host's fold ceiling before any commit
2369
+ * (see `./capacity.ts`), throwing as {@link throwRefusal} does when they
2370
+ * would grow the collection past it.
2371
+ *
2372
+ * The returned admission re-runs the verb's decisions at commit time.
2373
+ * Each commit passes `next()` to `Writer.commit`, which hands back every
2374
+ * log entry in `[fromSeq, seq)`: the entries this decision has not seen.
2375
+ *
2376
+ * - **Row (EvalPlanQual).** A planned `U` / `D` whose row any entry
2377
+ * committed after the read touched (in this window, or in an earlier
2378
+ * row's window of the same batch) is re-decided from the newest version,
2379
+ * or skipped; see {@link VerbWrite}. A rebased post-image is the verdict's `body`,
2380
+ * so the writer commits it.
2381
+ * - **Capacity (main-10 G5-race).** An empty window with no rebase means
2382
+ * nothing intervened, so the decision stands as made and nothing is
2383
+ * recomputed. Otherwise the decision re-runs over the read's tail plus
2384
+ * the window, for the planned writes not yet committed (this one with
2385
+ * its rebased post-image), and a refusal throws before the committing
2386
+ * create, so concurrent growth writes that each passed this check cannot
2387
+ * together pass the ceiling.
2388
+ *
2389
+ * Each `committed(entry)` moves `fromSeq` past this batch's own commit, so
2390
+ * the writer reads only entries this decision has not seen.
2391
+ *
2392
+ * With no folded state (an unprovisioned collection), the collection is empty,
2393
+ * so the pre-commit check is skipped; a re-check starts from an empty
2394
+ * collection.
2395
+ *
2396
+ * @param read The pre-commit read: its folded state, and `tail`, the
2397
+ * first empty log slot it folded through.
2398
+ */
2399
+ const admitWrites = async (ctx, read, verbWrites) => {
2400
+ const { folded } = read;
2401
+ const writes = verbWrites.map((w) => w.planned);
2402
+ let forceMaintenance = false;
2403
+ let warning;
2404
+ if (folded !== void 0) {
2405
+ const decision = capacityDecision({
2406
+ collection: ctx.collectionName,
2407
+ head: folded.head,
2408
+ base: folded.base,
2409
+ tail: folded.tail,
2410
+ writes,
2411
+ ceilings: currentFoldCeilings()
2412
+ });
2413
+ if (decision.refusal !== void 0) return await throwRefusal(ctx, decision, read.tail);
2414
+ forceMaintenance = decision.pressure;
2415
+ warning = decision.warning;
2416
+ }
2417
+ const head = folded?.head ?? EMPTY_HEAD;
2418
+ const base = folded?.base ?? /* @__PURE__ */ new Map();
2419
+ const seen = [...folded?.tail ?? []];
2420
+ const sinceRead = [];
2421
+ let fromSeq = read.tail;
2422
+ let pending = 0;
2423
+ let lastWindow = [];
2424
+ let pressure = forceMaintenance;
2425
+ let lastCommitted;
2426
+ let lastSkipped = false;
2427
+ const check = async (window, tail) => {
2428
+ lastWindow = window;
2429
+ const { planned, rebase, stillMatches } = verbWrites[pending];
2430
+ let rebased;
2431
+ if (planned.op !== "I") {
2432
+ const newest = newestVersion([...sinceRead, ...window], ctx.collectionName, planned.docId);
2433
+ if (newest === "gone") throw new RowSkipped(planned.docId);
2434
+ if (newest !== void 0 && stillMatches !== void 0 && !stillMatches(newest)) throw new RowSkipped(planned.docId);
2435
+ if (newest !== void 0 && rebase !== void 0) {
2436
+ rebased = await rebase(newest);
2437
+ if (rebased === void 0) throw new RowSkipped(planned.docId);
2438
+ }
2439
+ }
2440
+ if (window.length === 0 && rebased === void 0) return;
2441
+ const tailNow = [
2442
+ ...seen,
2443
+ ...sinceRead,
2444
+ ...window
2445
+ ];
2446
+ const remaining = writes.slice(pending);
2447
+ if (rebased !== void 0) remaining[0] = {
2448
+ ...planned,
2449
+ after: rebased
2450
+ };
2451
+ const decision = capacityDecision({
2452
+ collection: ctx.collectionName,
2453
+ head,
2454
+ base,
2455
+ tail: tailNow,
2456
+ writes: remaining.map((write) => withLiveBefore(write, ctx.collectionName, tailNow)),
2457
+ ceilings: currentFoldCeilings()
2458
+ });
2459
+ if (decision.refusal !== void 0) return await throwRefusal(ctx, decision, tail);
2460
+ warning = decision.warning;
2461
+ pressure = decision.pressure;
2462
+ return {
2463
+ forceMaintenance: decision.pressure && pending === writes.length - 1,
2464
+ ...rebased !== void 0 && { body: rebased }
2465
+ };
2466
+ };
2467
+ return {
2468
+ forceMaintenance,
2469
+ next: () => {
2470
+ lastWindow = [];
2471
+ return {
2472
+ fromSeq,
2473
+ check
2474
+ };
2475
+ },
2476
+ committed: (entry) => {
2477
+ sinceRead.push(...lastWindow, entry);
2478
+ fromSeq = entry.seq + 1;
2479
+ pending++;
2480
+ lastCommitted = entry;
2481
+ lastSkipped = false;
2482
+ },
2483
+ skipped: () => {
2484
+ pending++;
2485
+ lastSkipped = true;
2486
+ },
2487
+ settle: async () => {
2488
+ if (!lastSkipped || lastCommitted === void 0 || !pressure || getCurrentContext()?.maintenance?.disabled === true) return;
2489
+ await dispatchWriteTick({
2490
+ storage: ctx.storage,
2491
+ currentJsonKey: `${ctx.collectionPrefix}/current.json`,
2492
+ collection: ctx.collectionName,
2493
+ prevSeq: lastCommitted.seq,
2494
+ observedTail: lastCommitted.seq + 1,
2495
+ forceFold: true
2496
+ });
2497
+ },
2498
+ warn: () => {
2499
+ if (warning !== void 0 && writes.length > 0) noteCapacityWarning(warning);
2500
+ }
2501
+ };
2502
+ };
2503
+ /**
2504
+ * `write` with `before` re-read from the latest entry for its row in
2505
+ * `tail`, when there is one: an intervening commit may have changed the
2506
+ * row, so growth (G3) is judged against the row as it now stands. A row an
2507
+ * intervening `D` removed has no `before`, which counts as growth (fails
2508
+ * closed).
2509
+ */
2510
+ const withLiveBefore = (write, collection, tail) => {
2511
+ if (write.op !== "U") return write;
2512
+ for (let i = tail.length - 1; i >= 0; i--) {
2513
+ const entry = tail[i];
2514
+ if (isOwnCollection(entry.collection, collection) && entry.doc_id === write.docId) {
2515
+ const { before: _stale, ...rest } = write;
2516
+ return entry.op === "D" || entry.after === void 0 ? rest : {
2517
+ ...rest,
2518
+ before: entry.after
2519
+ };
2520
+ }
2521
+ }
2522
+ return write;
2523
+ };
2524
+ /**
2525
+ * `Collection.insert` implementation. Mints a UUIDv7 `_id`
2526
+ * when the caller omits it (or supplies an empty string); honours a
2527
+ * caller-supplied non-empty `_id`. The first `I` for an `_id` wins:
2528
+ * when a live row already holds the `_id`, the insert throws
2529
+ * non-retriable `BaerlyError{code:"AlreadyExists"}` and commits nothing.
2530
+ * A row committed before the pre-commit check read is caught there,
2531
+ * without a writer round-trip; one committed concurrently, after that
2532
+ * read, is caught by the writer's insert guard, which reads the log
2533
+ * window the check could not see. So of concurrent inserts of one `_id`,
2534
+ * at most one commits (exactly one, absent storage failures) and the
2535
+ * others throw `AlreadyExists` — matches the
2536
+ * locked `Collection.insert` contract
2537
+ * (`packages/protocol/src/collection-api.ts`).
2538
+ *
2539
+ * The emitted `LogEntry` has `op:"I"` and `after === {...doc, _id}`
2540
+ * (today's per-doc-replace model).
2541
+ *
2542
+ * **SDK-minted replay.** `opts.mintedId` marks `_id` as minted by an SDK
2543
+ * client rather than chosen by the caller; only the HTTP insert route
2544
+ * sets it (from the body's `mintedId`), and `Collection.insert` never
2545
+ * does. With it set, a live row for `_id` equal to `{...doc, _id}`
2546
+ * (`insertReplaysRow`: key order ignored) is this insert's own earlier
2547
+ * success, resent after a lost response: the call returns `{ _id }` and
2548
+ * commits nothing, whether the check read or the writer's insert guard
2549
+ * finds the row. A live row with any other body still throws
2550
+ * `AlreadyExists`. "Live" covers a `U`: a body equal to a later update's
2551
+ * post-image also replays. A caller-chosen `_id` never replays, even onto
2552
+ * an identical row, so a run-once guard like
2553
+ * `insert({ _id: "migration-x", done: true })` has at most one winner.
2554
+ *
2555
+ * @throws BaerlyError code="AlreadyExists" — a live row holds `_id`,
2556
+ * committed before or concurrently with this call (and, with
2557
+ * `mintedId`, its body differs). `err._id` is the `_id`. Not retriable.
2558
+ * @throws BaerlyError code="InvalidConfig" — `doc` holds a value JSON
2559
+ * cannot store as written (see `assertDocumentValues`), the post-image
2560
+ * `{ ...doc, _id }` encodes to more than `MAX_DOCUMENT_BYTES` (see
2561
+ * `assertDocumentSize`), the supplied
2562
+ * `_id` is present and not a string (`null` included), the resolved `_id` fails
2563
+ * {@link assertDocId} (key-segment rule, an unpaired surrogate, or not NFC), or `opts.mintedId`
2564
+ * is set and is not the resolved `_id`. Checked before I/O.
2565
+ * @throws BaerlyError code="WriteConflict" — a rejected storage precondition
2566
+ * `Writer.commit()` does not resolve, or log retention retired part of the
2567
+ * window the insert guard had to read; nothing was committed. Retriable.
2568
+ * @throws BaerlyError code="AmbiguousCommit" — a committing create may be
2569
+ * durable, but its outcome could not be resolved. The row may or may not
2570
+ * have been inserted. Not retriable-by-default; see `Writer.commit`.
2571
+ * @throws BaerlyError code="SchemaError" — `doc` nests deeper than
2572
+ * `MAX_DOCUMENT_DEPTH` (see `assertDocumentValues`), checked before I/O;
2573
+ * or from the per-collection `SchemaValidator` threaded via
2574
+ * `collectionReadContext`.
2575
+ *
2576
+ * @internal — exported for `Collection.insert` in `./collection.ts` to delegate
2577
+ * without duplicating the auto-id / collision-check /
2578
+ * commit pipeline.
2579
+ */
2580
+ const runInsert = async (ctx, doc, opts) => {
2581
+ const supplied = doc["_id"];
2582
+ callerFacingCheck(() => {
2583
+ assertInsertIdType(supplied);
2584
+ assertDocumentValues(doc, "insert");
2585
+ });
2586
+ const _id = typeof supplied === "string" && supplied.length > 0 ? supplied : uuidv7();
2587
+ callerFacingCheck(() => assertDocId(_id));
2588
+ const mintedId = opts?.mintedId;
2589
+ if (mintedId !== void 0 && mintedId !== _id) throw new BaerlyError("InvalidConfig", `insert: mintedId ${JSON.stringify(mintedId)} is not the document _id ${JSON.stringify(_id)}`);
2590
+ const body = {
2591
+ ...doc,
2592
+ _id
2593
+ };
2594
+ callerFacingCheck(() => assertDocumentSize(body, "insert"));
2595
+ if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, body, {
2596
+ collection: ctx.collectionName,
2597
+ verb: "insert"
2598
+ });
2599
+ const existing = await runReadRows(ctx, {
2600
+ wire: { clauses: [{
2601
+ op: "eq",
2602
+ field: "_id",
2603
+ value: _id
2604
+ }] },
2605
+ order: void 0,
2606
+ limit: 1
2607
+ });
2608
+ const live = existing.rows[0];
2609
+ if (live !== void 0) {
2610
+ if (mintedId !== void 0 && insertReplaysRow(body, live.doc)) {
2611
+ recordInsertReplay(ctx.collectionName);
2612
+ return { _id };
2613
+ }
2614
+ throw insertAlreadyExists(ctx.collectionName, _id);
2615
+ }
2616
+ const admission = await admitWrites(ctx, existing, [{ planned: {
2617
+ op: "I",
2618
+ docId: _id,
2619
+ after: body
2620
+ } }]);
2621
+ await writerFor(ctx).commit({
2622
+ op: "I",
2623
+ collection: ctx.collectionName,
2624
+ docId: _id,
2625
+ body,
2626
+ insertGuard: {
2627
+ absentBelowSeq: existing.tail,
2628
+ replayIdentical: mintedId !== void 0
2629
+ },
2630
+ admission: admission.next(),
2631
+ ...admission.forceMaintenance && { forceMaintenance: true }
2632
+ });
2633
+ admission.warn();
2634
+ return { _id };
2635
+ };
2636
+ /**
2637
+ * The `doc_id` that `update` / `delete` commit a materialised row under,
2638
+ * after checking that the row's own `_id` is that same string. Every
2639
+ * stored `I` / `U` post-image names its storage key; a row whose `_id` is
2640
+ * missing, not a string, or a different id is stored corruption (an older
2641
+ * release let a patch strip or re-key `_id`). Committing it anyway would
2642
+ * duplicate the row under its `_id`, or tombstone a key that does not
2643
+ * hold it, so it fails loud instead. `replace(id, doc)` repairs such a
2644
+ * row: it forces `_id` to `id`.
2645
+ *
2646
+ * @throws BaerlyError code="InvalidResponse" — the row's `_id` is not the
2647
+ * string it is stored under.
2648
+ */
2649
+ const storedRowId = (row, verb) => {
2650
+ const id = row.doc["_id"];
2651
+ if (id !== row.docId) throw new BaerlyError("InvalidResponse", `Query.${verb}: stored row ${JSON.stringify(row.docId)} carries _id ${typeof id === "string" ? JSON.stringify(id) : `of type ${typeof id}`}; repair it with replace(id, doc)`);
2652
+ return row.docId;
2653
+ };
2654
+ /**
2655
+ * Reject a merge patch that would change a row's `_id`. A patch whose
2656
+ * top-level `_id` is present (not `undefined`, which `merge` treats as
2657
+ * absent) must equal the row's id: an equal `_id` keeps a full-document
2658
+ * round-trip patch working, while any other value — including `null`,
2659
+ * which would strip `_id` — is a caller bug. Unlike `replace`, which takes
2660
+ * the id as a separate argument and forces it onto the document, a patch
2661
+ * has no separate id to fall back on, so forcing it would hide the bug.
2662
+ *
2663
+ * @throws BaerlyError code="InvalidConfig" — the patch names a different `_id`.
2664
+ */
2665
+ const assertPatchKeepsId = (patch, docId) => {
2666
+ if (patch === null || typeof patch !== "object" || Array.isArray(patch)) return;
2667
+ if (!Object.hasOwn(patch, "_id")) return;
2668
+ const patchId = patch["_id"];
2669
+ if (patchId !== void 0 && patchId !== docId) throw markCallerFacing(new BaerlyError("InvalidConfig", `Query.update: a patch cannot change _id (row ${JSON.stringify(docId)}); omit _id from the patch`, { resolution: PATCH_ID_RESOLUTION }));
2670
+ };
2671
+ /**
2672
+ * `applyMergePatch(row, patch)` as `update` commits it, validated against the
2673
+ * collection's schema.
2674
+ *
2675
+ * @throws BaerlyError code="InvalidConfig" — the post-image holds a value
2676
+ * JSON cannot store as written (see `assertDocumentValues`), or encodes
2677
+ * to more than `MAX_DOCUMENT_BYTES` (see `assertDocumentSize`).
2678
+ * @throws BaerlyError code="SchemaError" — the merge produced `undefined`,
2679
+ * the post-image nests deeper than `MAX_DOCUMENT_DEPTH`, or the schema
2680
+ * rejected the post-image.
2681
+ */
2682
+ const mergeAndValidate = async (ctx, row, patch) => {
2683
+ const merged = applyMergePatch(row, patch);
2684
+ if (merged === void 0) throw new BaerlyError("SchemaError", `Query.update: merge produced undefined for doc ${JSON.stringify(row["_id"])}`);
2685
+ callerFacingCheck(() => assertDocumentValues(merged, "update", { undefinedMembersAbsent: true }));
2686
+ callerFacingCheck(() => assertDocumentSize(merged, "update"));
2687
+ if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, merged, {
2688
+ collection: ctx.collectionName,
2689
+ verb: "update"
2690
+ });
2691
+ return merged;
2692
+ };
2693
+ /**
2694
+ * `Query.update` implementation. Materialises the predicate/order/
2695
+ * limit-filtered match set, applies RFC 7396 `applyMergePatch(prev, patch)`
2696
+ * per row, and emits one `op:"U"` `LogEntry` per affected `doc_id`
2697
+ * — one `Writer.commit()` round-trip apiece.
2698
+ *
2699
+ * Atomicity is per row, not across the N-row batch: each affected row
2700
+ * commits independently — the document is the atomic unit; there is no
2701
+ * multi-row batch.
2702
+ *
2703
+ * **Concurrent writes to a matched row (EvalPlanQual).** When another
2704
+ * write to a matched row commits between this read and the row's own
2705
+ * commit, the patch is re-applied to that newest version and the
2706
+ * predicate re-evaluated on it (`limit` / `order` are not); a row that
2707
+ * was deleted there, or no longer matches, is skipped and not counted in
2708
+ * `modified`. See {@link VerbWrite}.
2709
+ *
2710
+ * `replica_identity` defaults to `PATCH_ONLY` for every collection
2711
+ * today — emitted `U` entries carry `{ after }` (the full post-image)
2712
+ * and neither `before` nor `key_old`. Consumers rebuilding pre-images
2713
+ * under `PATCH_ONLY` need to maintain a shadow table — see
2714
+ * `packages/protocol/src/log.ts:102–118`.
2715
+ *
2716
+ * @throws BaerlyError code="WriteConflict" — one row's commit hit a rejected
2717
+ * storage precondition `Writer.commit()` does not resolve. The
2718
+ * partial-progress `modified` count is NOT returned in that case.
2719
+ * @throws BaerlyError code="AmbiguousCommit" — one row's committing create
2720
+ * may be durable, but its outcome could not be resolved. Rows before it in
2721
+ * the batch are already applied and that row's own fate is unknown; the
2722
+ * partial-progress `modified` count is NOT returned. Re-read rows by `_id`
2723
+ * before deciding whether to resume; absence does not prove a create failed.
2724
+ * See `Writer.commit`.
2725
+ * @throws BaerlyError code="SchemaError" — `applyMergePatch(prev, patch)` produced
2726
+ * `undefined` (defensive — `MergePatch<T>` cannot be `null` at the
2727
+ * root in the type system), the patch (checked before I/O) or a merged
2728
+ * post-image nests deeper than `MAX_DOCUMENT_DEPTH`, or the schema
2729
+ * rejected a post-image; at a
2730
+ * row's commit (re-applied to a newer version) rows before it are
2731
+ * already applied.
2732
+ * @throws BaerlyError code="InvalidConfig" — the patch (checked before
2733
+ * I/O) or a merged post-image holds a value JSON cannot store as written
2734
+ * (see `assertDocumentValues`; an `undefined` member is absent), a merged
2735
+ * post-image encodes to more than `MAX_DOCUMENT_BYTES` (see
2736
+ * `assertDocumentSize`; a row stored larger may still shrink), or the
2737
+ * patch names an `_id` other than the row's (see {@link assertPatchKeepsId}), or the row's
2738
+ * `_id` holds an unpaired surrogate or is not NFC (see {@link assertDocId}). Checked for every matched
2739
+ * row, with schema validation, before any row commits.
2740
+ * @throws BaerlyError code="CapacityExceeded" — the batch would grow the
2741
+ * collection past the serving host's fold ceiling (see `./capacity.ts`);
2742
+ * decided before any row commits, and re-checked at each row's commit
2743
+ * when a concurrent write landed since (see {@link admitWrites}), in
2744
+ * which case rows before it are already applied. Also thrown when the
2745
+ * request's storage budget runs out (the request ledger, including the
2746
+ * writer's commit-resolution reserve): rows before the refused one are
2747
+ * applied, it and the rows after it are not, and nothing is ambiguous.
2748
+ * The partial-progress `modified` count is NOT returned.
2749
+ * @throws BaerlyError code="InvalidResponse" — a matched stored row's
2750
+ * `_id` is not the string it is stored under.
2751
+ */
2752
+ const runUpdate = async (ctx, state, patch) => {
2753
+ callerFacingCheck(() => assertDocumentValues(patch, "update", { undefinedMembersAbsent: true }));
2754
+ const read = await runReadRows(ctx, state);
2755
+ const { rows } = read;
2756
+ const planned = [];
2757
+ for (const row of rows) {
2758
+ const doc = row.doc;
2759
+ const docId = storedRowId(row, "update");
2760
+ assertPatchKeepsId(patch, docId);
2761
+ assertDocId(docId);
2762
+ const merged = await mergeAndValidate(ctx, doc, patch);
2763
+ planned.push({
2764
+ docId,
2765
+ before: doc,
2766
+ merged
2767
+ });
2768
+ }
2769
+ const stillMatches = state.wire === void 0 ? void 0 : compileWire(state.wire);
2770
+ const rebase = async (latest) => {
2771
+ if (stillMatches !== void 0 && !stillMatches(latest)) return;
2772
+ return await mergeAndValidate(ctx, latest, patch);
2773
+ };
2774
+ const admission = await admitWrites(ctx, read, planned.map((p) => ({
2775
+ planned: {
2776
+ op: "U",
2777
+ docId: p.docId,
2778
+ after: p.merged,
2779
+ before: p.before
2780
+ },
2781
+ rebase
2782
+ })));
2783
+ let modified = 0;
2784
+ for (const [i, { docId, merged }] of planned.entries()) {
2785
+ let entry;
2786
+ try {
2787
+ ({entry} = await writerFor(ctx).commit({
2788
+ op: "U",
2789
+ collection: ctx.collectionName,
2790
+ docId,
2791
+ body: merged,
2792
+ admission: admission.next(),
2793
+ ...admission.forceMaintenance && i === planned.length - 1 && { forceMaintenance: true }
2794
+ }));
2795
+ } catch (error) {
2796
+ if (error instanceof RowSkipped) {
2797
+ admission.skipped();
2798
+ continue;
2799
+ }
2800
+ throw error;
2801
+ }
2802
+ admission.committed(entry);
2803
+ modified++;
2804
+ }
2805
+ await admission.settle();
2806
+ admission.warn();
2807
+ return { modified };
2808
+ };
2809
+ /**
2810
+ * `Collection.replace` implementation. Existence check via `runRead` over
2811
+ * a `byId`-shaped wire so the `singleIdFromPredicate` PK fast path
2812
+ * (`Map.get`) fires. Missing row → `NotFound` directly (no conflict-string
2813
+ * indirection through the router). Present row → emit a single
2814
+ * `op:"U"` `LogEntry` carrying `doc` as the post-image, with `_id`
2815
+ * forced to the requested `id` so doc identity is preserved across
2816
+ * replaces even if the supplied `doc._id` differs.
2817
+ *
2818
+ * A replace racing another write to the row stays last-writer-wins: an
2819
+ * update committed after this read is overwritten. A delete committed
2820
+ * there is not undone: the replace commits nothing and throws `NotFound`
2821
+ * (see {@link VerbWrite}).
2822
+ *
2823
+ * @throws BaerlyError code="NotFound" — no row exists at `id`, including
2824
+ * one a concurrent delete removed after this call's read.
2825
+ * @throws BaerlyError code="InvalidConfig" — `id` fails
2826
+ * {@link assertDocId} (key-segment rule, an unpaired surrogate, or not NFC), or `doc` holds a
2827
+ * value JSON cannot store as written (see `assertDocumentValues`), or
2828
+ * `{ ...doc, _id: id }` encodes to more than `MAX_DOCUMENT_BYTES` (see
2829
+ * `assertDocumentSize`). Checked before I/O.
2830
+ * @throws BaerlyError code="SchemaError" — `doc` nests deeper than
2831
+ * `MAX_DOCUMENT_DEPTH` (checked before I/O), or the post-image is
2832
+ * rejected by the collection's bound validator.
2833
+ * @throws BaerlyError code="WriteConflict" — a rejected storage precondition
2834
+ * `Writer.commit()` does not resolve; nothing was committed.
2835
+ * @throws BaerlyError code="AmbiguousCommit" — a committing create may be
2836
+ * durable, but its outcome could not be resolved, so the replace may or may
2837
+ * not have been applied. Re-read the row by `id` before deciding whether to
2838
+ * retry; absence does not prove the create failed. See `Writer.commit`.
2839
+ */
2840
+ const runReplaceById = async (ctx, id, doc) => {
2841
+ callerFacingCheck(() => assertDocId(id));
2842
+ callerFacingCheck(() => assertDocumentValues(doc, "replace"));
2843
+ const body = {
2844
+ ...doc,
2845
+ _id: id
2846
+ };
2847
+ callerFacingCheck(() => assertDocumentSize(body, "replace"));
2848
+ const read = await runReadRows(ctx, {
2849
+ wire: { clauses: [{
2850
+ op: "eq",
2851
+ field: "_id",
2852
+ value: id
2853
+ }] },
2854
+ order: void 0,
2855
+ limit: void 0
2856
+ });
2857
+ const current = read.rows[0];
2858
+ if (current === void 0) throw new BaerlyError("NotFound", `No such row: ${id}`);
2859
+ if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, body, {
2860
+ collection: ctx.collectionName,
2861
+ verb: "replace"
2862
+ });
2863
+ const admission = await admitWrites(ctx, read, [{ planned: {
2864
+ op: "U",
2865
+ docId: id,
2866
+ after: body,
2867
+ before: current.doc
2868
+ } }]);
2869
+ try {
2870
+ await writerFor(ctx).commit({
2871
+ op: "U",
2872
+ collection: ctx.collectionName,
2873
+ docId: id,
2874
+ body,
2875
+ admission: admission.next(),
2876
+ ...admission.forceMaintenance && { forceMaintenance: true }
2877
+ });
2878
+ } catch (error) {
2879
+ if (error instanceof RowSkipped) throw new BaerlyError("NotFound", `No such row: ${id}`);
2880
+ throw error;
2881
+ }
2882
+ admission.warn();
2883
+ };
2884
+ /**
2885
+ * `Query.delete` implementation. Tombstones every matched row with a
2886
+ * single `op:"D"` `LogEntry` per `doc_id`. `replica_identity` defaults
2887
+ * to `PATCH_ONLY`, so emitted `D` entries carry no body fields
2888
+ * (no `after`, no `before`/`key_old`).
2889
+ * Consumers rebuilding pre-images under `PATCH_ONLY` need to
2890
+ * maintain a shadow table — see `packages/protocol/src/log.ts:102–118`.
2891
+ *
2892
+ * Atomicity is per row, not across the N-row batch — same shape as
2893
+ * `Query.update`. The document is the atomic unit; there is no
2894
+ * multi-row batch.
2895
+ *
2896
+ * **Concurrent writes to a matched row (EvalPlanQual).** As in
2897
+ * `runUpdate`: when another write to a matched row commits between this
2898
+ * read and the row's own commit, the predicate is re-evaluated on that
2899
+ * newest version. A row deleted there (including by a racing delete, or
2900
+ * deleted and re-inserted), or no longer matching, is skipped and not
2901
+ * counted in `deleted`. See {@link VerbWrite}.
2902
+ *
2903
+ * @throws BaerlyError code="WriteConflict" — one row's commit hit a rejected
2904
+ * storage precondition `Writer.commit()` does not resolve. The
2905
+ * partial-progress `deleted` count is NOT returned
2906
+ * in that case.
2907
+ * @throws BaerlyError code="AmbiguousCommit" — one row's committing create
2908
+ * may be durable, but its outcome could not be resolved. Rows before it in
2909
+ * the batch are already tombstoned and that row's own fate is unknown; the
2910
+ * partial-progress `deleted` count is NOT returned. Re-read rows by `_id`
2911
+ * before deciding whether to resume. See `Writer.commit`.
2912
+ * @throws BaerlyError code="CapacityExceeded" — as in `runUpdate`: the
2913
+ * batch would grow past the fold ceiling (a delete can when a pending
2914
+ * fold cannot make progress), or the request's storage budget ran out
2915
+ * part-way. Rows before the refused one are tombstoned, it and the rows
2916
+ * after it are not; the partial-progress `deleted` count is NOT returned.
2917
+ * @throws BaerlyError code="InvalidResponse" — a matched stored row's
2918
+ * `_id` is not the string it is stored under.
2919
+ */
2920
+ const runDelete = async (ctx, state) => {
2921
+ const read = await runReadRows(ctx, state);
2922
+ const docIds = read.rows.map((row) => storedRowId(row, "delete"));
2923
+ const stillMatches = state.wire === void 0 ? void 0 : compileWire(state.wire);
2924
+ const admission = await admitWrites(ctx, read, docIds.map((docId) => ({
2925
+ planned: {
2926
+ op: "D",
2927
+ docId
2928
+ },
2929
+ stillMatches
2930
+ })));
2931
+ let deleted = 0;
2932
+ for (const [i, docId] of docIds.entries()) {
2933
+ let entry;
2934
+ try {
2935
+ ({entry} = await writerFor(ctx).commit({
2936
+ op: "D",
2937
+ collection: ctx.collectionName,
2938
+ docId,
2939
+ admission: admission.next(),
2940
+ ...admission.forceMaintenance && i === docIds.length - 1 && { forceMaintenance: true }
2941
+ }));
2942
+ } catch (error) {
2943
+ if (error instanceof RowSkipped) {
2944
+ admission.skipped();
2945
+ continue;
2946
+ }
2947
+ throw error;
2948
+ }
2949
+ admission.committed(entry);
2950
+ deleted++;
2951
+ }
2952
+ await admission.settle();
2953
+ admission.warn();
2954
+ return { deleted };
2955
+ };
2956
+ /**
2957
+ * Load `current.json` fresh, walk `[log_seq_start, tail_hint)` in parallel, fold
2958
+ * per-`doc_id`, then apply predicate / order / limit in memory.
2959
+ *
2960
+ * Error mapping:
2961
+ * - `current.json` missing → empty result (collection not provisioned).
2962
+ * - `current.json` malformed → `InvalidResponse` (from `readCurrentJson`).
2963
+ * - log entry missing in `[log_seq_start, tail_hint)` → `Internal`.
2964
+ * - log entry malformed → `InvalidResponse`.
2965
+ */
2966
+ const runRead = async (ctx, state, opts) => {
2967
+ const budget = new ReadBudget(ctx.collectionName);
2968
+ const countOnly = opts?.countOnly === true;
2969
+ const { rows, count, manifestPointer, fresh } = await runReadRows(ctx, state, budget, countOnly);
2970
+ if (!countOnly) budget.admitOutput(rows.length);
2971
+ return {
2972
+ rows: rows.map((row) => row.doc),
2973
+ count,
2974
+ manifestPointer,
2975
+ fresh
2976
+ };
2977
+ };
2978
+ /**
2979
+ * {@link runRead}, keeping each row's storage key. Every call, a write
2980
+ * verb's pre-commit read included, records its work (see
2981
+ * {@link recordReadWork}).
2982
+ */
2983
+ const runReadRows = async (ctx, state, budget = new ReadBudget(ctx.collectionName, {}), countOnly = false) => {
2984
+ const currentJsonKey = `${ctx.collectionPrefix}/current.json`;
2985
+ const head = await readCurrentJson(ctx.storage, currentJsonKey);
2986
+ const fresh = true;
2987
+ if (head === null) {
2988
+ recordReadWork(ctx.collectionName, 0, 0, 0);
2989
+ return {
2990
+ rows: [],
2991
+ count: 0,
2992
+ manifestPointer: "m1:0000000000000",
2993
+ fresh,
2994
+ tail: 0
2995
+ };
2996
+ }
2997
+ budget.admitHead(head.json);
2998
+ const hint = head.json.tail_hint;
2999
+ const logSeqStart = logSeqStartOf(head.json);
3000
+ const baseDocs = head.json.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.json.snapshot, ctx.collectionName);
3001
+ const probeFrom = Math.max(logSeqStart, hint);
3002
+ const entries = await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, hint, { onBody: budget.chargeTailBody });
3003
+ const probe = await probeReadTail(ctx.storage, ctx.collectionPrefix, probeFrom, {
3004
+ pool: budget.requestPool,
3005
+ onBody: budget.chargeTailBody,
3006
+ refusal: budget.probeRefusal
3007
+ });
3008
+ const tail = probe.tail;
3009
+ const docs = new Map(baseDocs);
3010
+ foldLogEntriesOnto(docs, entries, { collection: ctx.collectionName });
3011
+ foldLogEntriesOnto(docs, probe.entries, { collection: ctx.collectionName });
3012
+ const fastId = singleIdFromPredicate(state.wire);
3013
+ let rows = [];
3014
+ let count;
3015
+ if (countOnly && fastId === void 0) count = limitedLength(countMatches(docs, state.wire), state.limit);
3016
+ else {
3017
+ if (fastId !== void 0) {
3018
+ const hit = docs.get(fastId);
3019
+ rows = hit === void 0 ? [] : [{
3020
+ docId: fastId,
3021
+ doc: hit
3022
+ }];
3023
+ } else rows = filterRows(docs, state.wire);
3024
+ if (state.order !== void 0) rows = orderRows(rows, state.order, state.limit);
3025
+ count = rows.length = limitedLength(rows.length, state.limit);
3026
+ }
3027
+ recordReadWork(ctx.collectionName, baseDocs.size + entries.length + probe.entries.length, docs.size, count);
3028
+ return {
3029
+ rows,
3030
+ count,
3031
+ manifestPointer: serializeManifestPointer(head.json, tail),
3032
+ fresh,
3033
+ tail,
3034
+ folded: {
3035
+ head: head.json,
3036
+ base: baseDocs,
3037
+ tail: [...entries, ...probe.entries]
3038
+ }
3039
+ };
3040
+ };
3041
+ /**
3042
+ * Emit one read's work onto the request's canonical line (the
3043
+ * `db.read.*` counters; units in `@baerly/protocol`'s `MetricsRecorder`
3044
+ * catalog). Takes counts the read already holds, so it adds no storage
3045
+ * call and no pass over the rows. Outside an observability scope it
3046
+ * returns before allocating anything; inside one it adds three
3047
+ * recorder rows per read.
3048
+ *
3049
+ * @param decoded Snapshot rows plus log entries decoded by the fold.
3050
+ * @param live Documents live after the fold, before predicate and limit.
3051
+ * @param returned Rows left after predicate, order and limit.
3052
+ */
3053
+ const recordReadWork = (collection, decoded, live, returned) => {
3054
+ const recorder = getCurrentContext()?.recorder;
3055
+ if (recorder === void 0) return;
3056
+ const labels = { collection };
3057
+ recorder.counter("db.read.decoded_entries_total", decoded, labels);
3058
+ recorder.counter("db.read.live_documents_total", live, labels);
3059
+ recorder.counter("db.read.returned_rows_total", returned, labels);
3060
+ };
3061
+ // packages/server/src/db-read-seams.ts
3062
+ /**
3063
+ * Manifest and log read seams over a {@link Db}: the collection read
3064
+ * context the HTTP router drives, and the `current.json` / log reads the
3065
+ * `/v1/since` handler makes. Module functions rather than `Db` methods so
3066
+ * the manifest and probe types stay off the public `Db` class; reached
3067
+ * outside this package through `@baerly/server/_internal/kernel`.
3068
+ *
3069
+ * Kept apart from `./db.ts` so the HTTP entry imports these without
3070
+ * pulling in the `Db` class and the collection API.
3071
+ */
3072
+ /**
3073
+ * Physical-key prefix for a `(app, tenant)` pair. Trailing slash is
3074
+ * part of the prefix so a caller's `list("")` resolves to
3075
+ * `list("app/<app>/tenant/<tenant>/")` and cannot enumerate a sibling
3076
+ * tenant whose name shares a prefix.
3077
+ */
3078
+ const physicalPrefixFor = (app, tenant) => `app/${app}/tenant/${tenant}/`;
3079
+ /** Private-field accessor, registered by the `Db` static block. */
3080
+ let internalsOf;
3081
+ /** Called once, from the `Db` static block. */
3082
+ const registerDbInternals = (accessor) => {
3083
+ internalsOf = accessor;
3084
+ };
3085
+ /**
3086
+ * Build a freshly-seeded {@link CollectionReadContext} for `name`. The
3087
+ * HTTP router uses this so it can drive `runAllWithMeta` directly
3088
+ * (the return shape carries the manifest-pointer cursor used to
3089
+ * pack `_meta` onto the read response envelope). Application
3090
+ * callers should keep using
3091
+ * {@link Db.collection}; the chainable terminals destructure the cursor
3092
+ * out and discard it to keep the locked `Query<T>` signature.
3093
+ *
3094
+ * Runs the same `name`-validation guard as {@link Db.collection}.
3095
+ *
3096
+ * @throws BaerlyError code="InvalidConfig" when `name` is empty,
3097
+ * contains `/`, is `"."` or `".."`, contains control characters,
3098
+ * starts with the reserved `"_"` prefix, exceeds 256 bytes, or is
3099
+ * not in Unicode Normalization Form C.
3100
+ * @internal
3101
+ */
3102
+ const collectionReadContext = (db, name) => {
3103
+ assertKeySegment(name, "collection", "Db.collection");
3104
+ const schema = internalsOf(db).schemas.get(name);
3105
+ return {
3106
+ storage: internalsOf(db).storage,
3107
+ collectionPrefix: `${physicalPrefixFor(db.app, db.tenant)}manifests/${name}`,
3108
+ collectionName: name,
3109
+ ...schema !== void 0 ? { schema } : {}
3110
+ };
3111
+ };
3112
+ /**
3113
+ * Read + parse this `Db`'s `manifests/<collection>/current.json`. Returns
3114
+ * `null` when the collection has not been provisioned yet (no
3115
+ * `current.json` exists). Throws `BaerlyError{code:"InvalidResponse"}`
3116
+ * on a malformed body — same contract as the underlying
3117
+ * {@link readCurrentJson} helper in `@baerly/protocol`.
3118
+ *
3119
+ * Backs the `/v1/since` long-poll handler in
3120
+ * `packages/server/src/http/since.ts`; that handler needs the parsed
3121
+ * `CurrentJson` plus an ETag for the follow-up reads.
3122
+ *
3123
+ * @internal — typed seam for the HTTP handler; app code should use
3124
+ * the collection API.
3125
+ */
3126
+ const getCurrentJson = async (db, collection, opts) => {
3127
+ assertNameSegment(collection, "collection");
3128
+ const key = `${physicalPrefixFor(db.app, db.tenant)}manifests/${collection}/current.json`;
3129
+ return readCurrentJson(internalsOf(db).storage, key, opts);
3130
+ };
3131
+ /**
3132
+ * Read + parse one `LogEntry` by `seq` from
3133
+ * `manifests/<collection>/log/<seq>.json`. Returns `null`
3134
+ * when the entry is missing — this typically means the GC sweeper
3135
+ * deleted the entry between a `readCurrentJson` and this GET (the
3136
+ * `/v1/since` handler treats the race as silent and skips the
3137
+ * entry). Throws `BaerlyError{code:"InvalidResponse"}` on a body
3138
+ * that isn't valid JSON.
3139
+ *
3140
+ * `current` is the manifest this read is floored against — pass the
3141
+ * same one the `seq` was derived from. It is a parameter rather than
3142
+ * caller-enforced discipline so a new caller cannot introduce a
3143
+ * sub-floor read: entries below `current.log_seq_start` are folded
3144
+ * into the snapshot and may already be reclaimed (invariant 5 in
3145
+ * `docs/spec/sync-protocol.md`).
3146
+ *
3147
+ * @throws BaerlyError code="Internal" — `seq` is below
3148
+ * `current.log_seq_start`, or below the certified prefix bound
3149
+ * `current.log_delete_floor` (a distinct message: the object is
3150
+ * gone, not merely reclaimable).
3151
+ *
3152
+ * @throws BaerlyError code="InvalidConfig" — the entry names a
3153
+ * canonically-equivalent but byte-different collection (a
3154
+ * legacy non-NFC spelling on R2); see `isOwnCollection`.
3155
+ *
3156
+ * @internal — typed seam for the HTTP handler; app code should use
3157
+ * the collection API.
3158
+ */
3159
+ const getLogEntry = async (db, collection, seq, current, opts) => {
3160
+ assertNameSegment(collection, "collection");
3161
+ assertAtOrAboveLogFloor("getLogEntry", seq, current);
3162
+ const key = logObjectKey(`${physicalPrefixFor(db.app, db.tenant)}manifests/${collection}`, seq);
3163
+ const got = await internalsOf(db).storage.get(key, opts);
3164
+ if (got === null) return null;
3165
+ let parsed;
3166
+ try {
3167
+ parsed = decodeJsonBytes(got.body);
3168
+ } catch (error) {
3169
+ throw new BaerlyError("InvalidResponse", `log entry at ${key}: body is not valid JSON`, { cause: error });
3170
+ }
3171
+ const entry = parsed;
3172
+ isOwnCollection(entry.collection, collection);
3173
+ return entry;
3174
+ };
3175
+ /**
3176
+ * Forward-probe at most `cap` committed log entries from `hint` and
3177
+ * return them. Unlike {@link probeLogTail}, reaching `cap` is not an
3178
+ * error: the chunk comes back as `kind: "at-least"`, a prefix of the
3179
+ * entries past `hint`, so a caller with a bounded request budget can
3180
+ * deliver it and resume after its last entry. A slot GET the request
3181
+ * ledger refuses ends the chunk the same way, keeping the entries read
3182
+ * before it. Each slot is one GET; size `cap` with `forwardProbeCap`.
3183
+ *
3184
+ * @throws BaerlyError code="Internal" — `hint` is below the floor, as
3185
+ * for {@link probeLogTail}.
3186
+ * @throws BaerlyError code="InvalidResponse" — an occupied slot does
3187
+ * not hold valid JSON.
3188
+ * @throws BaerlyError code="InvalidConfig" — an entry names a
3189
+ * canonically-equivalent but byte-different collection, as for
3190
+ * {@link getLogEntry}.
3191
+ *
3192
+ * @internal — typed seam for the HTTP handler.
3193
+ */
3194
+ const probeLogChunk = async (db, collection, hint, current, opts) => {
3195
+ assertNameSegment(collection, "collection");
3196
+ assertAtOrAboveLogFloor("probeLogChunk", hint, current);
3197
+ const logPrefix = `${physicalPrefixFor(db.app, db.tenant)}manifests/${collection}`;
3198
+ const chunk = await probeTailChunk(internalsOf(db).storage, logPrefix, hint, {
3199
+ ...opts,
3200
+ stopOnRefusal: true
3201
+ });
3202
+ for (const entry of chunk.entries) isOwnCollection(entry.collection, collection);
3203
+ return chunk;
3204
+ };
3205
+ /**
3206
+ * Guard a log-read seq against both floors on the manifest it was
3207
+ * derived from.
3208
+ *
3209
+ * Entries below `log_seq_start` have been folded into the snapshot
3210
+ * (invariant 5 in `docs/spec/sync-protocol.md`) and may be reclaimed at
3211
+ * any time, so a sub-floor read is never a legitimate request — it is
3212
+ * either a stale seq the caller failed to screen, or a caller that
3213
+ * never screened at all. Both are protocol-invariant violations by
3214
+ * internal code, hence `Internal` rather than `InvalidConfig`: no
3215
+ * client input reaches these seams unscreened (`/v1/since` rejects a
3216
+ * sub-floor cursor with `CursorExpired` before ever getting here).
3217
+ *
3218
+ * Below `log_delete_floor` the contiguous prefix is certified deleted,
3219
+ * so the object is not merely *reclaimable* but already *reclaimed*.
3220
+ * The two floors get distinct messages. Same code, because both are the
3221
+ * same class of caller bug; different wording, because an operator
3222
+ * reading the throw has to know whether the bytes are recoverable.
3223
+ *
3224
+ * The floors arrive as the whole `CurrentJson` rather than as bare
3225
+ * numbers so neither can be invented independently of the manifest.
3226
+ *
3227
+ * Loud on purpose. PostgreSQL removed `old_snapshot_threshold` in PG17
3228
+ * because a fixed reclamation window that let a reader proceed
3229
+ * *silently* produced wrong answers; Oracle's `ORA-01555` is the same
3230
+ * trade and survives because it throws.
3231
+ */
3232
+ const assertAtOrAboveLogFloor = (seam, seq, current) => {
3233
+ const floor = logSeqStartOf(current);
3234
+ const storedDeleteFloor = logDeleteFloorOf(current);
3235
+ const deleteFloor = certifiedDeleteFloor(current);
3236
+ if (deleteFloor > 0 && seq < deleteFloor) {
3237
+ const clamped = storedDeleteFloor === deleteFloor ? "" : ` (stored log_delete_floor=${storedDeleteFloor}, clamped to log_seq_start=${floor})`;
3238
+ throw new BaerlyError("Internal", `${seam}: seq ${seq} is below the certified delete floor ${deleteFloor}${clamped}; the log object is GONE — it has been reclaimed, not merely made reclaimable`);
3239
+ }
3240
+ if (seq < floor) throw new BaerlyError("Internal", `${seam}: seq ${seq} is below the fold floor log_seq_start=${floor}; entries beneath the floor are folded into the snapshot and may already be reclaimed`);
3241
+ };
3242
+ /**
3243
+ * Guard an app, tenant, or collection name used as a path-segment in the
3244
+ * bucket-key encoding. Routes through {@link assertNameSegment}: the
3245
+ * shared {@link assertPathSegment} rule (empty / `"/"` / `"."`|`".."` /
3246
+ * C0-C1 control / leading `"_"` (ADR-003) / overlong) plus Unicode
3247
+ * Normalization Form C, all as `BaerlyError{code:"InvalidConfig"}`.
3248
+ * `role` and `verb` are baked into the message so the caller doesn't
3249
+ * need to format their own.
3250
+ *
3251
+ * Used by {@link Db.create} (twice — `app`, `tenant`) and
3252
+ * {@link collectionReadContext} (once — `name`).
3253
+ *
3254
+ * @internal
3255
+ */
3256
+ const assertKeySegment = (value, role, verb) => {
3257
+ assertNameSegment(value, role, verb);
3258
+ };
3259
+ export { probeLogChunk as a, runAllWithMeta as c, runReplaceById as d, CAPACITY_WARNING_FIELD as f, getLogEntry as i, runByIdWithMeta as l, validateWire as m, collectionReadContext as n, registerDbInternals as o, assertReadDocId as p, getCurrentJson as r, makeQuery as s, assertKeySegment as t, runInsert as u };
3260
+
3261
+ //# sourceMappingURL=db-read-seams-BSs0m1z1.js.map