@gusto/baerly-storage 0.2.0 → 0.4.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 (155) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +29 -0
  3. package/README.md +176 -70
  4. package/dist/API.md +213 -139
  5. package/dist/CHANGELOG.md +434 -0
  6. package/dist/RECIPES.md +125 -0
  7. package/dist/THIRD-PARTY-LICENSES.txt +238 -0
  8. package/dist/{app-config-C0Bbw_Z6.d.ts → app-config-DyiFK3_k.d.ts} +55 -11
  9. package/dist/app-config.d.ts +1 -1
  10. package/dist/auth.d.ts +1 -1
  11. package/dist/auth.js +301 -301
  12. package/dist/auth.js.map +1 -1
  13. package/dist/aws4fetch.esm-p7eEzLCs.js +1702 -0
  14. package/dist/aws4fetch.esm-p7eEzLCs.js.map +1 -0
  15. package/dist/baerly.js +35 -15
  16. package/dist/baerly.js.map +1 -1
  17. package/dist/baerly.spec.json +342 -0
  18. package/dist/bytes-BXdamO3L.js.map +1 -1
  19. package/dist/{client-DYZfoZb9.d.ts → client-Fe8CwB73.d.ts} +10 -10
  20. package/dist/client-react.d.ts +3 -3
  21. package/dist/client-react.js +4 -4
  22. package/dist/client-react.js.map +1 -1
  23. package/dist/client.d.ts +4 -4
  24. package/dist/client.js +3 -3
  25. package/dist/client.js.map +1 -1
  26. package/dist/{cloudflare-CINJPKCW.js → cloudflare-DzKBrUlg.js} +178 -2
  27. package/dist/cloudflare-DzKBrUlg.js.map +1 -0
  28. package/dist/cloudflare.d.ts +49 -6
  29. package/dist/cloudflare.js +59 -26
  30. package/dist/cloudflare.js.map +1 -1
  31. package/dist/config-1tv0-Yzm.js +2693 -0
  32. package/dist/config-1tv0-Yzm.js.map +1 -0
  33. package/dist/constants-CfeMWQWk.js +222 -0
  34. package/dist/constants-CfeMWQWk.js.map +1 -0
  35. package/dist/context-DRZ3tZ5l.js.map +1 -1
  36. package/dist/{cost-CQt1YRkA.js → cost-DSMIVqzL.js} +43 -42
  37. package/dist/cost-DSMIVqzL.js.map +1 -0
  38. package/dist/current-json-C6nhPOm1.js +190 -0
  39. package/dist/current-json-C6nhPOm1.js.map +1 -0
  40. package/dist/{db-BM3y2JQw.d.ts → db-DsPkOVEH.d.ts} +26 -108
  41. package/dist/{deploy-CrAbfgCq.js → deploy-DonTr-CV.js} +12 -5
  42. package/dist/deploy-DonTr-CV.js.map +1 -0
  43. package/dist/dev-vite.d.ts +11 -7
  44. package/dist/dev-vite.js +7 -6
  45. package/dist/dev-vite.js.map +1 -1
  46. package/dist/dev.d.ts +1 -1
  47. package/dist/dev.js +1 -1
  48. package/dist/{doctor-Db-hzPmE.js → doctor-DSIyCDg_.js} +14 -136
  49. package/dist/doctor-DSIyCDg_.js.map +1 -0
  50. package/dist/{dump-BYA55NLP.js → dump-Bh5k26VQ.js} +10 -31
  51. package/dist/dump-Bh5k26VQ.js.map +1 -0
  52. package/dist/{errors-DOdL95kK.js → errors-Dfa3p78c.js} +25 -5
  53. package/dist/errors-Dfa3p78c.js.map +1 -0
  54. package/dist/{export-Bhbz90-z.js → export-DtF5tDIM.js} +11 -32
  55. package/dist/{export-Bhbz90-z.js.map → export-DtF5tDIM.js.map} +1 -1
  56. package/dist/{fsck-CPPZWt9p.js → fsck-D_djMO5D.js} +28 -39
  57. package/dist/fsck-D_djMO5D.js.map +1 -0
  58. package/dist/{http-Cw8p6y5b.js → http-DxM9MflO.js} +151 -79
  59. package/dist/http-DxM9MflO.js.map +1 -0
  60. package/dist/http.d.ts +42 -26
  61. package/dist/http.js +3 -2
  62. package/dist/{index-DwDTWPSU.d.ts → index-0rZcMBwy.d.ts} +10 -7
  63. package/dist/{index-C3JAH1Yo.d.ts → index-B6oexfOB.d.ts} +9 -9
  64. package/dist/{index-cUY-36AN.d.ts → index-BNRh23K9.d.ts} +21 -5
  65. package/dist/{index-DSvwEUeF.d.ts → index-BYk9oCNf.d.ts} +240 -202
  66. package/dist/index.d.ts +6 -6
  67. package/dist/index.js +5 -5
  68. package/dist/{indexes-DAu2AkTW.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
  69. package/dist/{inspect-Bdbzvi-_.js → inspect-6WZ-pC7-.js} +21 -36
  70. package/dist/inspect-6WZ-pC7-.js.map +1 -0
  71. package/dist/key-Di6yyxFu.js +35 -0
  72. package/dist/key-Di6yyxFu.js.map +1 -0
  73. package/dist/{snapshot-SS8USDUF.js → log-tail-D98U1JBo.js} +179 -84
  74. package/dist/log-tail-D98U1JBo.js.map +1 -0
  75. package/dist/{maintenance-ClzBC1Vv.js → maintenance-B4Dki6Ig.js} +438 -176
  76. package/dist/maintenance-B4Dki6Ig.js.map +1 -0
  77. package/dist/{maintenance-BRrThz8V.d.ts → maintenance-B_e0T99L.d.ts} +114 -26
  78. package/dist/{maintenance-BvOv6BMM.js → maintenance-C7coQp4c.js} +217 -94
  79. package/dist/maintenance-C7coQp4c.js.map +1 -0
  80. package/dist/maintenance.d.ts +3 -2
  81. package/dist/maintenance.js +3 -2
  82. package/dist/node.d.ts +176 -68
  83. package/dist/node.js +3 -2
  84. package/dist/{normalize-XWY25_sG.js → normalize-rjnZLwS4.js} +2 -2
  85. package/dist/normalize-rjnZLwS4.js.map +1 -0
  86. package/dist/{observability-CpOiEN0k.js → observability-wzs3-BL_.js} +279 -109
  87. package/dist/observability-wzs3-BL_.js.map +1 -0
  88. package/dist/observability.d.ts +3 -3
  89. package/dist/observability.js +1 -1
  90. package/dist/{plan-DOTl21vq.js → plan-a7PJHBCy.js} +7 -4
  91. package/dist/plan-a7PJHBCy.js.map +1 -0
  92. package/dist/{query-BmiQy328.js → query-rAtXNQQB.js} +1063 -1202
  93. package/dist/query-rAtXNQQB.js.map +1 -0
  94. package/dist/{rebuild-index-DC_nR6wP.js → rebuild-index-BVzQSZlm.js} +10 -32
  95. package/dist/rebuild-index-BVzQSZlm.js.map +1 -0
  96. package/dist/{request-BEF_OvMh.js → request-u0M51mhJ.js} +3 -3
  97. package/dist/{request-BEF_OvMh.js.map → request-u0M51mhJ.js.map} +1 -1
  98. package/dist/restore-R-4rbciV.js +778 -0
  99. package/dist/restore-R-4rbciV.js.map +1 -0
  100. package/dist/runtime-spec-qL3_lTTU.js +391 -0
  101. package/dist/runtime-spec-qL3_lTTU.js.map +1 -0
  102. package/dist/s3-http-B-z8th6O.d.ts +60 -0
  103. package/dist/s3.d.ts +47 -0
  104. package/dist/s3.js +45 -0
  105. package/dist/s3.js.map +1 -0
  106. package/dist/{shared-secret-BJdSwpgw.js → shared-secret-DgEicd3x.js} +13 -5
  107. package/dist/shared-secret-DgEicd3x.js.map +1 -0
  108. package/dist/src-BG20LZs7.js +2271 -0
  109. package/dist/src-BG20LZs7.js.map +1 -0
  110. package/dist/{src-zhEAmmF7.js → src-CYHFDrKz.js} +82 -99
  111. package/dist/src-CYHFDrKz.js.map +1 -0
  112. package/dist/{src-QQ7jDeL2.js → src-DYZ4H1aF.js} +44 -23
  113. package/dist/src-DYZ4H1aF.js.map +1 -0
  114. package/dist/subcommand-DoDA-K7d.js +197 -0
  115. package/dist/subcommand-DoDA-K7d.js.map +1 -0
  116. package/dist/time-DUqvFMHq.js +119 -0
  117. package/dist/time-DUqvFMHq.js.map +1 -0
  118. package/dist/{usage-CLjirdD-.js → usage-DBV1eQHC.js} +7 -22
  119. package/dist/usage-DBV1eQHC.js.map +1 -0
  120. package/dist/{validate-DCq_0DIn.js → validate-DtljsCh1.js} +51 -51
  121. package/dist/{validate-DCq_0DIn.js.map → validate-DtljsCh1.js.map} +1 -1
  122. package/dist/wire-izfGZDvr.js.map +1 -1
  123. package/package.json +77 -42
  124. package/dist/cloudflare-CINJPKCW.js.map +0 -1
  125. package/dist/config-DVfDGyw1.js +0 -278
  126. package/dist/config-DVfDGyw1.js.map +0 -1
  127. package/dist/cost-CQt1YRkA.js.map +0 -1
  128. package/dist/current-json-C-EyJqs0.js +0 -354
  129. package/dist/current-json-C-EyJqs0.js.map +0 -1
  130. package/dist/deploy-CrAbfgCq.js.map +0 -1
  131. package/dist/doctor-Db-hzPmE.js.map +0 -1
  132. package/dist/dump-BYA55NLP.js.map +0 -1
  133. package/dist/errors-DOdL95kK.js.map +0 -1
  134. package/dist/fsck-CPPZWt9p.js.map +0 -1
  135. package/dist/http-Cw8p6y5b.js.map +0 -1
  136. package/dist/inspect-Bdbzvi-_.js.map +0 -1
  137. package/dist/maintenance-BvOv6BMM.js.map +0 -1
  138. package/dist/maintenance-ClzBC1Vv.js.map +0 -1
  139. package/dist/normalize-XWY25_sG.js.map +0 -1
  140. package/dist/observability-CpOiEN0k.js.map +0 -1
  141. package/dist/plan-DOTl21vq.js.map +0 -1
  142. package/dist/query-BmiQy328.js.map +0 -1
  143. package/dist/rebuild-index-DC_nR6wP.js.map +0 -1
  144. package/dist/restore-C6IcmLeA.js +0 -771
  145. package/dist/restore-C6IcmLeA.js.map +0 -1
  146. package/dist/shared-secret-BJdSwpgw.js.map +0 -1
  147. package/dist/snapshot-SS8USDUF.js.map +0 -1
  148. package/dist/src-DU1sCMlr.js +0 -6236
  149. package/dist/src-DU1sCMlr.js.map +0 -1
  150. package/dist/src-QQ7jDeL2.js.map +0 -1
  151. package/dist/src-zhEAmmF7.js.map +0 -1
  152. package/dist/subcommand-DZcHcsYp.js +0 -5122
  153. package/dist/subcommand-DZcHcsYp.js.map +0 -1
  154. package/dist/usage-CLjirdD-.js.map +0 -1
  155. /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
@@ -1,7 +1,9 @@
1
- import { i as readCurrentJson, m as MANIFEST_POINTER_EMPTY_SNAPSHOT, n as createCurrentJson, o as FORBIDDEN_MERGE_KEYS, r as logSeqStartOf, v as decodeJsonBytes, y as encodeJsonBytes } from "./current-json-C-EyJqs0.js";
2
- import { t as BaerlyError } from "./errors-DOdL95kK.js";
3
- import { C as matchesWire, S as assertWireSatisfiable, _ as encodeIndexValue, b as versionFromContent, d as loadSnapshotAsMap, g as allIndexKeysFor, h as walkLogRange, i as runBoundedMaintenance, m as readLogEntry, o as shouldFireMaintenance, p as foldLogEntriesOnto, r as dispatchInlineAwaited, v as validateIndexDefinition, w as deepEqualDocumentValue, x as validateWire } from "./maintenance-ClzBC1Vv.js";
4
- import { t as normalizePredicateArg } from "./normalize-XWY25_sG.js";
1
+ import { a as decodeJsonBytes, i as readCurrentJson, n as createCurrentJson, o as encodeJsonBytes, r as logSeqStartOf } from "./current-json-C6nhPOm1.js";
2
+ import { l as MAINTENANCE_PROFILE_CF_FREE, m as MAX_KEY_BYTES, r as FORBIDDEN_MERGE_KEYS, s as LOG_FORWARD_PROBE_CAP } from "./constants-CfeMWQWk.js";
3
+ import { t as BaerlyError } from "./errors-Dfa3p78c.js";
4
+ import { A as deepEqualDocumentValue, C as findLogTail, D as validateWire, E as versionFromContent, O as assertWireSatisfiable, S as assertNameNotReserved, T as logObjectKey, _ as encodeIndexValue, b as loadSnapshotAsMap, g as allIndexKeysFor, h as walkLogRange, i as dispatchInlineAwaited, k as matchesWire, l as shouldFireMaintenance, m as readLogEntry, p as foldLogEntriesOnto, s as runBoundedMaintenance, v as validateIndexDefinition, w as probeTailFrom } from "./maintenance-B4Dki6Ig.js";
5
+ import { t as normalizePredicateArg } from "./normalize-rjnZLwS4.js";
6
+ import { a as uuid, n as timestamp, o as uuidv7, r as countKey } from "./time-DUqvFMHq.js";
5
7
  import { i as noopMetricsRecorder, n as getCurrentContext } from "./context-DRZ3tZ5l.js";
6
8
  //#region packages/protocol/src/json.ts
7
9
  const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -79,1214 +81,1084 @@ const mergePredicateWires = (a, b) => {
79
81
  assertWireSatisfiable(merged);
80
82
  return merged;
81
83
  };
82
- //#endregion
83
- //#region packages/protocol/src/types.ts
84
- /**
85
- * Mint a fresh {@link UUID}. The cast lives here so callers don't sprinkle
86
- * `<UUID>crypto.randomUUID()` throughout the codebase.
87
- */
88
- const uuid = () => crypto.randomUUID();
89
- /**
90
- * Mint a UUIDv7 — 48-bit Unix-millis prefix + 74 bits of randomness,
91
- * formatted as a standard 8-4-4-4-12 UUID string per RFC 9562 §5.7.
92
- * Lex-sortable by mint time, so it pairs well with object-storage
93
- * list semantics. Returns a branded {@link UUID}.
94
- *
95
- * Uses `crypto.getRandomValues` which is universally available
96
- * (Node 19+, Workerd, Bun, browsers).
97
- *
98
- * @example
99
- * ```ts
100
- * const id = uuidv7();
101
- * // e.g. "01956cad-4cc8-7abc-9def-0123456789ab"
102
- * ```
103
- */
104
- const uuidv7 = () => {
105
- const millis = Date.now();
106
- const rand = new Uint8Array(10);
107
- crypto.getRandomValues(rand);
108
- rand[0] = rand[0] & 15 | 112;
109
- rand[2] = rand[2] & 63 | 128;
110
- const millisHex = millis.toString(16).padStart(12, "0");
111
- const b = Array.from(rand, (n) => n.toString(16).padStart(2, "0")).join("");
112
- return `${millisHex.slice(0, 8)}-${millisHex.slice(8, 12)}-${b.slice(0, 4)}-${b.slice(4, 8)}-${b.slice(8, 20)}`;
113
- };
84
+ const utf8$1 = new TextEncoder();
85
+ const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/;
114
86
  /**
115
- * Mint the trailing seq segment of an LSN (`<base32-time>_<sess>_<seq>`).
116
- * `COUNT_BIT_WIDTH = 10` (matches `packages/protocol/src/log.ts:145`)
117
- * gives a 2-char descending base-32 string with a domain of 0..1023.
118
- *
119
- * Used together with {@link timestamp} (the descending base-32
120
- * encoding of millis-since-epoch). See {@link uint2strDesc} for the
121
- * lex-reversal property both rely on.
87
+ * The single validation rule for every caller-controlled key segment
88
+ * (`_id`, `collection`, `app`, `tenant`) before it becomes a written
89
+ * key segment or `LocalFsStorage` path. Rejects empty / `"/"` /
90
+ * `"."`|`".."` / C0-C1 control / leading `"_"` (ADR-003) / `> MAX_SEGMENT_BYTES`,
91
+ * all as `BaerlyError{code:"InvalidConfig"}`.
92
+ *
93
+ * @param role human label for the segment ("_id" | "collection" | "app" | "tenant").
94
+ * @param verb optional calling-context label for the message.
122
95
  */
123
- const countKey = (number) => uint2strDesc(number, 10);
124
- const uint2str = (num, bits) => {
125
- const maxBase32Length = Math.ceil(bits / 5);
126
- return num.toString(32).padStart(maxBase32Length, "0");
96
+ const assertPathSegment = (value, role, verb = "") => {
97
+ const where = verb === "" ? role : `${verb}: ${role}`;
98
+ if (value.length === 0) throw new BaerlyError("InvalidConfig", `${where} must be a non-empty string`);
99
+ if (value.includes("/")) throw new BaerlyError("InvalidConfig", `${where} may not contain "/": ${JSON.stringify(value)}`);
100
+ if (value === "." || value === "..") throw new BaerlyError("InvalidConfig", `${where} may not be "." or "..": ${JSON.stringify(value)}`);
101
+ if (CONTROL_CHARS.test(value)) throw new BaerlyError("InvalidConfig", `${where} may not contain control characters`);
102
+ if (utf8$1.encode(value).length > 256) throw new BaerlyError("InvalidConfig", `${where} is too long (> 256 bytes)`);
103
+ assertNameNotReserved(value, where);
127
104
  };
105
+ //#endregion
106
+ //#region packages/server/src/doc-id.ts
128
107
  /**
129
- * Lex-reversed base-32 encoder for an unsigned integer in `[0, 2^bits)`.
130
- * Pads to `Math.ceil(bits/5)` chars so all values in the domain compare
131
- * lex against each other.
132
- *
133
- * **Order-reversal property:** for any pair of integers `a < b` (with
134
- * `a, b ∈ [0, 2^bits)`), `uint2strDesc(a, bits) > uint2strDesc(b, bits)`
135
- * lexicographically. Composed into an LSN of shape
136
- * `<base32-time>_<session>_<seq>` (where both `<base32-time>` and
137
- * `<seq>` use this encoder), a forward `Storage.list(prefix)`
138
- * returns log entries in reverse-causal order — newer entries first.
139
- *
140
- * This is the structural property the read path leans on:
141
- * `ListObjectsV2` is forward-only on S3, but the descending encoding
142
- * makes "fetch the K newest entries" a single bounded LIST with
143
- * `maxKeys=K` instead of a full-population LIST + in-memory reverse.
144
- *
145
- * Behaviourally verified across randomized populations in
146
- * `packages/protocol/src/lsn-reverse-list.test.ts`. Quantified
147
- * bytes-listed reduction is in
148
- * `docs/spec/attachments/lsn-reverse-walk-baseline.json`
149
- * (run `pnpm bench:lsn-reverse-walk` to reproduce). Spec rationale:
150
- * `docs/spec/sync-protocol.md` §"Subtleties of the manifest key".
108
+ * Guard a caller-supplied `_id` before it becomes a written key segment
109
+ * (index keys, log `doc_id`) or filesystem path (`LocalFsStorage`). The
110
+ * `_id` analogue of `assertKeySegment` (`db.ts`). Routes through the
111
+ * single shared {@link assertPathSegment} rule (empty / `"/"` /
112
+ * `"."`|`".."` / C0-C1 control chars / leading `"_"` (ADR-003) / overlong,
113
+ * all as `BaerlyError{code:"InvalidConfig"}`).
151
114
  */
152
- const uint2strDesc = (num, bits) => {
153
- return uint2str(Math.pow(2, bits) - 1 - num, bits);
154
- };
155
- const str2uintDesc = (str, bits) => {
156
- return Math.pow(2, bits) - 1 - parseInt(str, 32);
115
+ const assertDocId = (id) => {
116
+ assertPathSegment(id, "_id");
157
117
  };
158
118
  //#endregion
159
- //#region packages/protocol/src/time.ts
119
+ //#region packages/server/src/query-planner-implies.ts
160
120
  /**
161
- * Encode an epoch-millis instant as a lexicographically-DEScending
162
- * base-32 key (newer sorts first). The load-bearing LSN ordering
163
- * primitive — see {@link uint2strDesc}.
164
- *
165
- * `epoch` is REQUIRED and validated. There is no default: an argless
166
- * call used to encode `0`, which descending-sorts as the most-ancient
167
- * instant and would silently invert ordering. A non-finite, negative,
168
- * or out-of-range `epoch` (e.g. a broken `Date.now()` returning `NaN`)
169
- * would corrupt the key silently rather than fail loud, so it throws
170
- * `Internal` instead — this is an invariant violation, not caller config
171
- * (the only legitimate argument is `Date.now()`).
121
+ * Filtered-index implication checker — decides whether every
122
+ * document accepted by a query predicate is also accepted by a
123
+ * filtered index's predicate. The query planner uses the result to
124
+ * rank candidate indexes; see {@link "./query-planner.ts".planQuery}.
125
+ *
126
+ * Pure-function module: no I/O, no `Db` / `Storage` imports. Lives
127
+ * in `@baerly/server` (not in `@baerly/protocol`) because the
128
+ * planner is the only caller.
129
+ *
130
+ * Operates on the wire form: both inputs are {@link PredicateWire}s
131
+ * with clauses already grouped by `(op, field, value)`. The
132
+ * normaliser at `@baerly/protocol`'s `./query/normalize.ts` has
133
+ * already flattened nested literal sub-predicates into dotted-path
134
+ * `eq` clauses, so there is no recursion on nested objects here.
172
135
  */
173
- const timestamp = (epoch) => {
174
- if (!Number.isInteger(epoch) || epoch < 0 || epoch >= 2 ** 42) throw new BaerlyError("Internal", `timestamp(): epoch must be a non-negative integer < 2^42 (got ${epoch})`);
175
- return uint2strDesc(epoch, 42);
176
- };
177
136
  /**
178
- * Delay for `ms` milliseconds, with optional cancellation. If
179
- * `signal` aborts before the delay elapses, the returned promise
180
- * rejects with `signal.reason`. Used by `S3HttpStorage`'s retry
181
- * loop so shutdown can interrupt an in-flight backoff instead of
182
- * waiting for it to complete.
137
+ * Group a wire's clauses by `field` so the per-field implication
138
+ * check can reason over one bundle at a time. Inlined small helper
139
+ * (not exported) so the planner module doesn't need to expose its
140
+ * grouping helper as a cross-module contract.
183
141
  */
184
- const delay = (ms, signal) => new Promise((resolve, reject) => {
185
- if (signal?.aborted) {
186
- reject(signal.reason);
187
- return;
142
+ const groupByField = (wire) => {
143
+ const groups = /* @__PURE__ */ new Map();
144
+ for (const clause of wire.clauses) {
145
+ const bucket = groups.get(clause.field);
146
+ if (bucket === void 0) groups.set(clause.field, [clause]);
147
+ else bucket.push(clause);
188
148
  }
189
- const timer = setTimeout(resolve, ms);
190
- signal?.addEventListener("abort", () => {
191
- clearTimeout(timer);
192
- reject(signal.reason);
193
- }, { once: true });
194
- });
195
- //#endregion
196
- //#region packages/protocol/src/log.ts
197
- const COUNT_BIT_WIDTH = 10;
149
+ return groups;
150
+ };
198
151
  /**
199
- * Extract the `session` and `seq` embedded in an `lsn` of shape
200
- * `<base32-time>_<session>_<seq>`. The seq portion is decoded as a
201
- * descending base-32 integer (matches `countKey` in `./types`).
202
- *
203
- * Use this at the `/v1/since` cursor-decoding boundary, where a
204
- * client resumes from an opaque `SinceResponse.next_cursor` and no
205
- * `LogEntry` is in scope. When iterating `LogEntry` records, read
206
- * `entry.session` / `entry.seq` directly instead.
207
- *
208
- * Throws on malformed input; callers should pass only lsns minted
209
- * by `Writer.commit` (see
210
- * `packages/server/src/writer.ts`).
152
+ * Collapse a per-field clause list into an {@link OperatorBundle}.
153
+ * Returns `"unknown-shape"` when the group has more than one `in`
154
+ * clause (set-intersection at plan time is out of scope) or
155
+ * unrecognised ops slipping through (defensive — the validator
156
+ * already locked the op vocabulary). Multiple `eq` clauses on one
157
+ * field: the validator proves they all agree, so we pick the first.
158
+ * Multiple range clauses on one field: take the strictest bound
159
+ * (tightest `lo` = numerically largest; tightest `hi` = numerically
160
+ * smallest).
211
161
  */
212
- const lsnParts = (lsn) => {
213
- const parts = lsn.split("_");
214
- if (parts.length !== 3) throw new BaerlyError("InvalidResponse", `invalid lsn shape: ${lsn}`);
215
- return {
216
- session: parts[1],
217
- seq: str2uintDesc(parts[2], COUNT_BIT_WIDTH)
218
- };
162
+ const decodeGroup = (clauses) => {
163
+ const bundle = {};
164
+ for (const clause of clauses) {
165
+ const v = clause.value;
166
+ if (clause.op === "eq") bundle.eq = v;
167
+ else if (clause.op === "gte") {
168
+ const next = {
169
+ value: v,
170
+ inclusive: true
171
+ };
172
+ bundle.lo = tightestLo(bundle.lo, next);
173
+ } else if (clause.op === "gt") {
174
+ const next = {
175
+ value: v,
176
+ inclusive: false
177
+ };
178
+ bundle.lo = tightestLo(bundle.lo, next);
179
+ } else if (clause.op === "lte") {
180
+ const next = {
181
+ value: v,
182
+ inclusive: true
183
+ };
184
+ bundle.hi = tightestHi(bundle.hi, next);
185
+ } else if (clause.op === "lt") {
186
+ const next = {
187
+ value: v,
188
+ inclusive: false
189
+ };
190
+ bundle.hi = tightestHi(bundle.hi, next);
191
+ } else if (clause.op === "in") {
192
+ if (bundle.in !== void 0) return "unknown-shape";
193
+ if (!Array.isArray(v)) return "unknown-shape";
194
+ bundle.in = v;
195
+ } else return "unknown-shape";
196
+ }
197
+ return bundle;
198
+ };
199
+ const tightestLo = (existing, next) => {
200
+ if (existing === void 0) return next;
201
+ if (typeof existing.value !== typeof next.value) return existing;
202
+ if (next.value > existing.value) return next;
203
+ if (next.value < existing.value) return existing;
204
+ if (!next.inclusive && existing.inclusive) return next;
205
+ return existing;
206
+ };
207
+ const tightestHi = (existing, next) => {
208
+ if (existing === void 0) return next;
209
+ if (typeof existing.value !== typeof next.value) return existing;
210
+ if (next.value < existing.value) return next;
211
+ if (next.value > existing.value) return existing;
212
+ if (!next.inclusive && existing.inclusive) return next;
213
+ return existing;
219
214
  };
220
- //#endregion
221
- //#region packages/server/src/log-conflict-adoption.ts
222
215
  /**
223
- * Decide whether the entry already at `/log/<seq>.json` is the
224
- * writer's own prior in-flight attempt and may be adopted. Pure
225
- * function; no I/O. The caller performs the GET (when the log PUT
226
- * surfaces 412) and passes the read-back body in `ctx.existing`.
216
+ * Does the query's lower bound `loQ` (`undefined` if none) prove that
217
+ * every matching doc satisfies the filter's lower bound `loF`?
227
218
  *
228
- * @see {@link AdoptionDecision} for the return shape.
229
- * @see The soundness invariant in this module's header docstring.
219
+ * `loF.inclusive` true → need doc ≥ loF.value; `loF.inclusive` false →
220
+ * need doc > loF.value. A stricter `loQ` (numerically larger or with
221
+ * tighter inclusivity) always implies a looser `loF`.
230
222
  */
231
- const tryAdoptOwnSessionLogEntry = (ctx) => {
232
- if (ctx.batchSize !== 1) return {
233
- adopt: false,
234
- reason: "batch"
223
+ const lowerBoundImplies = (loF, loQ) => {
224
+ if (loQ === void 0) return false;
225
+ if (typeof loF.value !== typeof loQ.value) return false;
226
+ if (loQ.value > loF.value) return true;
227
+ if (loQ.value < loF.value) return false;
228
+ if (loF.inclusive) return true;
229
+ return !loQ.inclusive;
230
+ };
231
+ /** Mirror of lowerBoundImplies for upper bounds. */
232
+ const upperBoundImplies = (hiF, hiQ) => {
233
+ if (hiQ === void 0) return false;
234
+ if (typeof hiF.value !== typeof hiQ.value) return false;
235
+ if (hiQ.value < hiF.value) return true;
236
+ if (hiQ.value > hiF.value) return false;
237
+ if (hiF.inclusive) return true;
238
+ return !hiQ.inclusive;
239
+ };
240
+ const loFromQuery = (q) => {
241
+ if (q.eq !== void 0) return {
242
+ value: q.eq,
243
+ inclusive: true
235
244
  };
236
- if (ctx.existing.session !== ctx.self.session) return {
237
- adopt: false,
238
- reason: "foreign-session"
245
+ if (q.in !== void 0 && q.in.length > 0) return {
246
+ value: q.in.reduce((acc, v) => v < acc ? v : acc, q.in[0]),
247
+ inclusive: true
239
248
  };
240
- if (ctx.existing.seq !== ctx.self.seq) return {
241
- adopt: false,
242
- reason: "wrong-seq"
249
+ return q.lo;
250
+ };
251
+ const hiFromQuery = (q) => {
252
+ if (q.eq !== void 0) return {
253
+ value: q.eq,
254
+ inclusive: true
243
255
  };
244
- return {
245
- adopt: true,
246
- entry: ctx.existing
256
+ if (q.in !== void 0 && q.in.length > 0) return {
257
+ value: q.in.reduce((acc, v) => v > acc ? v : acc, q.in[0]),
258
+ inclusive: true
247
259
  };
260
+ return q.hi;
248
261
  };
249
- //#endregion
250
- //#region packages/server/src/writer.ts
251
262
  /**
252
- * `Writer` — stateless multi-instance write engine.
253
- *
254
- * Each {@link Writer.commit} call reads `current.json` FRESH from
255
- * the bucket, mints the next {@link LogEntry}, PUTs the content body
256
- * and the log entry, and CAS-advances `current.json` with `If-Match`.
257
- * Up to {@link S3_REQUEST_MAX_RETRIES} attempts on contention before
258
- * surfacing `BaerlyError{code:"Conflict"}`. The optional integrity
259
- * walk over the live log tail is gated by
260
- * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off
261
- * — see the option's docstring).
262
- *
263
- * The instance carries no per-write cache: every commit re-reads
264
- * `current.json`, so N stateless server instances writing the same
265
- * tenant prefix contend at exactly one place — the conditional PUT
266
- * on `current.json` — and one loses cleanly with a 412.
267
- *
268
- * **Manifest-first ordering is REVERSED relative to the legacy
269
- * `src/syncer.ts` write loop.** Old loop: PUT manifest → PUT content
270
- * → CAS. New loop: PUT content → PUT log entry → CAS-advance
271
- * `current.json`. A crashed mid-loop writer leaves an unreferenced
272
- * content body (no log entry points at it), not an orphan log entry
273
- * with missing content. The compactor sweeps the orphan content
274
- * later.
275
- *
276
- * **`LogEntry` shape.** Emitted entries follow the contract in
277
- * `packages/protocol/src/log.ts` (see {@link LogEntry}) and
278
- * `docs/spec/log-entry-shape.md`. The on-bucket key is
279
- * `log/<seq>.json` (the integer `seq` is the load-bearing
280
- * identifier; the `lsn` string is schema-only).
263
+ * Filtered-index implication checker — decides whether every document
264
+ * accepted by `queryWire` is also accepted by `indexFilterWire`. When
265
+ * `true`, a walk over an index declared with `predicate: indexFilterWire`
266
+ * is **complete** for `queryWire`: no matching doc is missing
267
+ * from the smaller key set, so the planner can prefer it.
281
268
  *
282
- * @see docs/spec/sync-protocol.md for the protocol invariants this
283
- * loop preserves.
284
- * @see docs/spec/log-entry-shape.md for the per-field contract.
285
- */
286
- const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
287
- const DEFAULT_INITIAL_BACKOFF_MS = 25;
288
- const MAX_BACKOFF_MS = 1500;
289
- const APPLICATION_JSON = "application/json";
290
- /**
291
- * Empty body for index entries. Each index entry is a fact ("doc
292
- * `<docId>` has `<field> = <value>`"), not data — readers list the
293
- * prefix, extract the doc id, then GET the content body separately.
294
- * Pre-allocated module-level constant so every index PUT shares one
295
- * zero-length buffer.
296
- */
297
- const EMPTY_BODY = new Uint8Array(0);
298
- /**
299
- * Stateless write engine for the multi-instance core.
269
+ * Implication on `eq`, `gt` / `gte`, `lt` / `lte`, and `in` is
270
+ * sound and complete in pure operator form; combined shapes (e.g.
271
+ * range-on-filter and `in`-on-query) follow the algebra in the body
272
+ * JSDoc.
300
273
  *
301
- * Construction is cheap and performs zero I/O — adapters build a
302
- * fresh `Writer` per request and discard it. All real work
303
- * happens in {@link commit}.
274
+ * Algorithm — group both wires by `field`, then for every field
275
+ * present in `indexFilterWire`:
304
276
  *
305
- * @example
306
- * ```ts
307
- * import { Writer } from "@gusto/baerly-storage";
308
- * import { MemoryStorage } from "@gusto/baerly-storage";
277
+ * 1. Decode the filter's clause group into an {@link OperatorBundle}.
278
+ * "unknown-shape" → refuse implication conservatively.
279
+ * 2. The query MUST have at least one clause on that field —
280
+ * otherwise the query says nothing about that field and cannot
281
+ * possibly imply the filter's constraint.
282
+ * 3. Decode the query's clause group on the same field.
283
+ * 4. For each non-empty slot of the filter bundle, the query bundle
284
+ * must establish the constraint:
285
+ * - `eq` → query establishes equality (via its own `eq`).
286
+ * - `in` → query is contained in the set (via `eq` ∈ set or
287
+ * `in` ⊆ set).
288
+ * - `lo` / `hi` → query establishes the bound via `eq`, `in`
289
+ * (then min/max of the set), or its own `lo`/`hi` with the
290
+ * inclusivity rules in {@link lowerBoundImplies} /
291
+ * {@link upperBoundImplies}.
292
+ * Mixed types (e.g. number filter vs string query) refuse
293
+ * implication conservatively.
309
294
  *
310
- * const writer = new Writer({
311
- * storage: new MemoryStorage(),
312
- * currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
313
- * });
295
+ * Returns `true` iff every clause was satisfied. An empty
296
+ * `indexFilterWire` is vacuously implied by any `queryWire`.
314
297
  *
315
- * const result = await writer.commit({
316
- * op: "I",
317
- * collection: "tickets",
318
- * docId: "doc-1",
319
- * body: { _id: "doc-1", title: "hello" },
320
- * });
321
- * console.log(result.entry.seq, result.attempts);
322
- * ```
298
+ * Soundness contract — when this function returns `true`,
299
+ * `matchesWire(queryWire, doc) ⇒ matchesWire(indexFilterWire, doc)` for
300
+ * any document `doc`. Tests pin this property; see
301
+ * `./query-planner-implies.test.ts`.
323
302
  */
324
- var Writer = class {
325
- #storage;
326
- #currentJsonKey;
327
- #maxRetries;
328
- #initialBackoffMs;
329
- #random;
330
- #indexes;
331
- #verifyLogIntegrityOnCommit;
332
- constructor(opts) {
333
- this.#storage = opts.storage;
334
- this.#currentJsonKey = opts.currentJsonKey;
335
- this.#maxRetries = opts.options?.maxRetries ?? 8;
336
- this.#initialBackoffMs = opts.options?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
337
- this.#random = opts.options?.random ?? Math.random;
338
- const indexes = opts.options?.indexes ?? [];
339
- for (const def of indexes) validateIndexDefinition(def);
340
- this.#indexes = indexes;
341
- this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
303
+ const predicateImplies = (indexFilterWire, queryWire) => {
304
+ const filterGroups = groupByField(indexFilterWire);
305
+ const queryGroups = groupByField(queryWire);
306
+ for (const [field, filterClauses] of filterGroups) {
307
+ const filterBundle = decodeGroup(filterClauses);
308
+ if (filterBundle === "unknown-shape") return false;
309
+ const queryClauses = queryGroups.get(field);
310
+ if (queryClauses === void 0) return false;
311
+ const queryBundle = decodeGroup(queryClauses);
312
+ if (queryBundle === "unknown-shape") return false;
313
+ if (filterBundle.eq !== void 0) {
314
+ if (queryBundle.eq === void 0) return false;
315
+ if (!deepEqualDocumentValue(queryBundle.eq, filterBundle.eq)) return false;
316
+ continue;
317
+ }
318
+ if (filterBundle.in !== void 0) {
319
+ const set = filterBundle.in;
320
+ const contains = (v) => set.some((m) => deepEqualDocumentValue(m, v));
321
+ if (queryBundle.eq !== void 0) {
322
+ if (!contains(queryBundle.eq)) return false;
323
+ } else if (queryBundle.in !== void 0) {
324
+ for (const v of queryBundle.in) if (!contains(v)) return false;
325
+ } else return false;
326
+ continue;
327
+ }
328
+ if (filterBundle.lo !== void 0) {
329
+ if (!lowerBoundImplies(filterBundle.lo, loFromQuery(queryBundle))) return false;
330
+ }
331
+ if (filterBundle.hi !== void 0) {
332
+ if (!upperBoundImplies(filterBundle.hi, hiFromQuery(queryBundle))) return false;
333
+ }
342
334
  }
343
- /**
344
- * Atomically commit one mutation. Reads `current.json` fresh, mints
345
- * the next log entry at `seq = current.next_seq`, PUTs the content
346
- * body and the log entry, then CAS-advances `current.json` with
347
- * `If-Match`. Retries on conflict up to `maxRetries`.
348
- *
349
- * The hot-path cost under no contention is 1 GET + 3 PUTs (4 ops);
350
- * an in-flight peer write costs one extra GET + the backoff sleep
351
- * per retry.
352
- *
353
- * Idempotency: PUT content uses `If-None-Match: "*"`, so a retry of
354
- * the same logical write produces the same content key and the
355
- * second PUT no-ops. PUT log entry also uses `If-None-Match: "*"`,
356
- * so two writers racing the same `next_seq` cause exactly one PUT
357
- * to land — the loser falls into the CAS retry path.
358
- *
359
- * @throws BaerlyError code="Conflict" when the retry budget is
360
- * exhausted (genuine high-contention case), or when the underlying
361
- * `current.json` CAS PUT lost.
362
- * @throws BaerlyError code="Conflict" — the writer fence
363
- * (`current.json.writer_fence.epoch`) was bumped by a concurrent
364
- * `claimWriter` call between this commit's read of
365
- * `current.json` and its CAS-advance. The stale writer aborts
366
- * to honour the new authority — the kernel does NOT retry under
367
- * the old epoch. See {@link claimWriter} for the rotation
368
- * recipe.
369
- * @throws BaerlyError code="Internal" when a log entry expected in
370
- * `[0, next_seq)` is missing — a protocol-invariant violation
371
- * (compactor bug or stale `current.json`).
372
- * @throws BaerlyError code="InvalidResponse" when a log-entry body
373
- * isn't valid JSON.
374
- *
375
- * **Implicit provisioning.** When `current.json` does not exist at
376
- * `currentJsonKey` (fresh bucket, fresh collection), the writer
377
- * auto-creates it with a zero-state manifest before the commit
378
- * lands. The cost is one extra Class A PUT on the very first
379
- * commit per collection; steady-state cost is unchanged. A peer
380
- * racing the same first-write loses cleanly on the create CAS
381
- * and re-reads to pick up the winner's manifest.
382
- */
383
- async commit(input) {
384
- const session = uuid().slice(0, 6);
385
- const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
386
- for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {
387
- let success;
388
- try {
389
- success = await this.#singleAttemptCommit([input], session, logPrefix, "Writer", true);
390
- } catch (error) {
391
- if (!isPreconditionFailed(error)) throw error;
392
- await this.#backoff(attempt);
335
+ return true;
336
+ };
337
+ /**
338
+ * Choose a query plan over the wire predicate + declared indexes.
339
+ * Pure function. The executor enforces the I/O semantics; the
340
+ * planner's only contract is "given these inputs, this is the
341
+ * routing decision."
342
+ *
343
+ * Algorithm:
344
+ * 1. `wire === undefined` or empty → `no-predicate`.
345
+ * 2. `indexes.length === 0` → `no-indexes-declared`.
346
+ * 3. Partition wire clauses per field into:
347
+ * - `equality[f] = v` from `eq` clauses.
348
+ * - `rangeOps[f] = {lo, hi, loInclusive, hiInclusive}` from
349
+ * one or more of `gt`/`gte`/`lt`/`lte` clauses on `f`.
350
+ * - `inOps[f] = [...]` from a single `in` clause on `f`.
351
+ * - Defensive: any field whose clause group mixes op-channels
352
+ * (mostly impossible post-validation) is marked unroutable
353
+ * and skipped — the executor's full-wire `matchesWire(...)`
354
+ * post-fetch catches the residue automatically.
355
+ * 4. If no equality / range / `in` candidates exist →
356
+ * `predicate-uses-operators-only`.
357
+ * 5. For each `def`, walk `def.on` left-to-right consuming
358
+ * equality clauses for each indexed field. On the FIRST field
359
+ * where the equality clause is absent, check whether a range
360
+ * or `in` clause is available for that field — if so, that's
361
+ * the "tail slot" of the walk.
362
+ * 6. Score candidates by `(equalityPrefixLen, hasTailExtension)`.
363
+ * Longest prefix wins; tail-extension breaks ties. If no
364
+ * candidate consumed at least one field (equality OR
365
+ * range/`in`): `no-matching-index`.
366
+ * 7. `in` FAN-OUT GUARD: if the chosen plan's `in` slot has
367
+ * `values.length > IN_FANOUT_THRESHOLD`, fall back to
368
+ * `FullScanPlan{reason:"no-matching-index"}` — N sequential
369
+ * LISTs cost more than a snapshot+log fold.
370
+ *
371
+ * The planner deliberately treats `def.on` as the LITERAL tuple of
372
+ * field names — top-level only. Dotted paths are out of scope here
373
+ * (the projector at `indexes.ts:projectIndexValues` is top-level-
374
+ * only too).
375
+ *
376
+ * **Range/`in` is allowed only on the LAST indexed field beyond the
377
+ * equality prefix** — on a composite `[a, b]`, a range on `a` with
378
+ * equality on `b` is NOT contiguous under the key encoding (the `b`
379
+ * slot sits to the right of the varying `a` slot). Clauses landing
380
+ * outside the tail slot are simply left for the executor's full-
381
+ * predicate re-check.
382
+ */
383
+ const planQuery = (wire, indexes) => {
384
+ if (wire === void 0 || wire.clauses.length === 0) return {
385
+ kind: "full-scan",
386
+ reason: "no-predicate"
387
+ };
388
+ if (indexes.length === 0) return {
389
+ kind: "full-scan",
390
+ reason: "no-indexes-declared"
391
+ };
392
+ const equality = /* @__PURE__ */ new Map();
393
+ const rangeOps = /* @__PURE__ */ new Map();
394
+ const inOps = /* @__PURE__ */ new Map();
395
+ const unroutable = /* @__PURE__ */ new Set();
396
+ const rangeAcc = /* @__PURE__ */ new Map();
397
+ for (const clause of wire.clauses) {
398
+ const field = clause.field;
399
+ if (unroutable.has(field)) continue;
400
+ if (clause.op === "eq") {
401
+ if (inOps.has(field) || rangeAcc.has(field)) {
402
+ unroutable.add(field);
403
+ equality.delete(field);
404
+ inOps.delete(field);
405
+ rangeAcc.delete(field);
393
406
  continue;
394
407
  }
395
- await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer");
396
- this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));
397
- return {
398
- entry: success.entries[0],
399
- currentEtag: success.currentEtag,
400
- attempts: attempt
401
- };
402
- }
403
- throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`);
404
- }
405
- /**
406
- * Single-attempt batched commit. Reads `current.json` ONCE, mints
407
- * `inputs.length` log entries with contiguous `seq` numbers
408
- * starting at the current `next_seq`, PUTs each content body and
409
- * each log entry, then CAS-advances `current.json` from
410
- * `next_seq = N` to `next_seq = N + inputs.length` with
411
- * `If-Match`.
412
- *
413
- * NO retry on CAS loss. On `current.json` 412, throws
414
- * `BaerlyError{code:"Conflict"}` immediately — the caller (here:
415
- * `Db.transaction`) decides whether to retry by re-running the
416
- * body, or to surface to the app. Likewise on a log-entry 412
417
- * (a peer wrote our seq).
418
- *
419
- * Empty `inputs`: returns `{ entries: [], currentEtag: undefined }`
420
- * after zero storage operations.
421
- *
422
- * @throws BaerlyError code="Conflict" — CAS lost on `current.json`,
423
- * or a log entry already exists at our seq (peer wrote ahead).
424
- * @throws BaerlyError code="Conflict" — the writer fence
425
- * (`current.json.writer_fence.epoch`) was bumped by a concurrent
426
- * `claimWriter` call between this batch's read of
427
- * `current.json` and its CAS-advance. The stale writer aborts
428
- * to honour the new authority — the kernel does NOT retry under
429
- * the old epoch. See {@link claimWriter} for the rotation
430
- * recipe.
431
- * @throws BaerlyError code="Internal" — protocol-invariant violation
432
- * (missing log entry inside `[0, next_seq)`).
433
- * @throws BaerlyError code="InvalidResponse" — malformed log body.
434
- *
435
- * **Implicit provisioning.** Like {@link commit}, this path auto-
436
- * creates `current.json` with a zero-state manifest on a missing
437
- * read. Because `commitBatch` does NOT retry on CAS loss, a peer
438
- * racing the same first-write surfaces `Conflict` to the caller
439
- * (`Db.transaction` re-runs the body); the manifest is durable
440
- * regardless of which writer won the create.
441
- */
442
- async commitBatch(inputs) {
443
- if (inputs.length === 0) return {
444
- entries: [],
445
- currentEtag: void 0
446
- };
447
- const session = uuid().slice(0, 6);
448
- const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
449
- const success = await this.#singleAttemptCommit(inputs, session, logPrefix, "Writer.commitBatch", false);
450
- await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer.commitBatch");
451
- this.#emitWriteMetrics(inputs[0].collection, success.classAOps);
452
- return {
453
- entries: success.entries,
454
- currentEtag: success.currentEtag
455
- };
456
- }
457
- /**
458
- * One full commit attempt — the shared body of {@link commit} and
459
- * {@link commitBatch}. Reads `current.json`, walks the log, mints N
460
- * entries, PUTs content + indexes in parallel, PUTs log entries,
461
- * CAS-advances `current.json`. Returns the success payload + the
462
- * pre-commit fence epoch so the caller can run
463
- * {@link #verifyFenceUnchanged} outside the retry-catch arm.
464
- *
465
- * Retryable failures (a peer wrote our seq; a peer won the CAS on
466
- * `current.json`) throw `BaerlyError{code:"Conflict"}`. The caller
467
- * catches via {@link isPreconditionFailed} and either retries
468
- * (`commit`) or surfaces (`commitBatch`). Fence-bump and protocol-
469
- * invariant violations are NOT thrown from this helper — the fence
470
- * check lives in the caller so its `Conflict` propagates past the
471
- * retry-catch arm. Other thrown `BaerlyError`s (Internal,
472
- * InvalidResponse, NetworkError) bypass `isPreconditionFailed` and
473
- * propagate naturally.
474
- *
475
- * Crash safety invariant: content / index PUTs are awaited before
476
- * log PUTs, which are awaited before the CAS. A crashed mid-attempt
477
- * writer leaves orphan content / index entries (no log entry
478
- * references them) — the compactor sweeps the orphans. The
479
- * inverse — orphan log entry with missing content — is never
480
- * produced.
481
- */
482
- async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix, adoptOwnSessionOnLogConflict) {
483
- const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
484
- const current = read.json;
485
- const baseEtag = read.etag;
486
- const expectedEpoch = current.writer_fence.epoch;
487
- if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.next_seq);
488
- const commitNowMs = Date.now();
489
- const commitTs = new Date(commitNowMs).toISOString();
490
- const lsnTimestamp = timestamp(commitNowMs);
491
- const entries = [];
492
- for (let i = 0; i < inputs.length; i++) {
493
- const input = inputs[i];
494
- const seq = current.next_seq + i;
495
- const entry = {
496
- lsn: `${lsnTimestamp}_${session}_${countKey(seq)}`,
497
- commit_ts: commitTs,
498
- op: input.op,
499
- collection: input.collection,
500
- doc_id: input.docId,
501
- session,
502
- seq,
503
- ...input.op !== "D" && input.body !== void 0 ? { after: input.body } : {},
504
- ...input.origin !== void 0 ? { origin: input.origin } : {}
505
- };
506
- entries.push(entry);
507
- }
508
- let contentPutCount = 0;
509
- let indexClassA = 0;
510
- const parallelPuts = [];
511
- const inBatchImage = /* @__PURE__ */ new Map();
512
- for (const input of inputs) {
513
- if (input.op !== "D" && input.body !== void 0) {
514
- contentPutCount++;
515
- const bytes = encodeJsonBytes(input.body);
516
- const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
517
- parallelPuts.push(this.#storage.put(contentKey, bytes, {
518
- ifNoneMatch: "*",
519
- contentType: APPLICATION_JSON
520
- }).catch((error) => {
521
- this.#observe429(error, input.collection);
522
- if (isPreconditionFailed(error)) return;
523
- throw error;
524
- }));
408
+ equality.set(field, clause.value);
409
+ } else if (clause.op === "in") {
410
+ if (equality.has(field) || rangeAcc.has(field) || inOps.has(field)) {
411
+ unroutable.add(field);
412
+ equality.delete(field);
413
+ inOps.delete(field);
414
+ rangeAcc.delete(field);
415
+ continue;
525
416
  }
526
- if (this.#indexes.length > 0) {
527
- let newKeys = [];
528
- let staleKeys = [];
529
- if (input.op === "I") newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
530
- else if (input.op === "U") {
531
- const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
532
- const oldKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
533
- newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
534
- const newSet = new Set(newKeys);
535
- staleKeys = oldKeys.filter((k) => !newSet.has(k));
536
- } else {
537
- const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
538
- staleKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
539
- }
540
- for (const k of newKeys) parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
541
- ifNoneMatch: "*",
542
- contentType: APPLICATION_JSON
543
- }).catch((error) => {
544
- this.#observe429(error, input.collection);
545
- if (isPreconditionFailed(error)) return;
546
- throw error;
547
- }));
548
- for (const k of staleKeys) parallelPuts.push(this.#storage.delete(k));
549
- indexClassA += newKeys.length + staleKeys.length;
550
- if (newKeys.length + staleKeys.length > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", newKeys.length + staleKeys.length, { collection: input.collection });
551
- inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
417
+ if (!Array.isArray(clause.value)) {
418
+ unroutable.add(field);
419
+ continue;
552
420
  }
553
- }
554
- await Promise.all(parallelPuts);
555
- const logPutOne = async (entry) => {
556
- const logEntryKey = `${logPrefix}/log/${entry.seq}.json`;
557
- const logBytes = encodeJsonBytes(entry);
558
- try {
559
- await this.#storage.put(logEntryKey, logBytes, {
560
- ifNoneMatch: "*",
561
- contentType: APPLICATION_JSON
562
- });
563
- return { ok: true };
564
- } catch (error) {
565
- this.#observe429(error, entry.collection);
566
- if (!isPreconditionFailed(error)) throw error;
567
- ctxMetrics().counter("db.r2.put.412_total", 1, {
568
- collection: entry.collection,
569
- step: "log-put"
570
- });
571
- return { ok: false };
421
+ inOps.set(field, clause.value);
422
+ } else {
423
+ if (equality.has(field) || inOps.has(field)) {
424
+ unroutable.add(field);
425
+ equality.delete(field);
426
+ inOps.delete(field);
427
+ rangeAcc.delete(field);
428
+ continue;
572
429
  }
573
- };
574
- const logPutResults = await Promise.all(entries.map(logPutOne));
575
- let committedEntries = entries;
576
- const firstConflictIdx = logPutResults.findIndex((r) => !r.ok);
577
- if (firstConflictIdx !== -1) {
578
- const conflictedEntry = entries[firstConflictIdx];
579
- const logEntryKey = `${logPrefix}/log/${conflictedEntry.seq}.json`;
580
- if (adoptOwnSessionOnLogConflict) {
581
- const decision = tryAdoptOwnSessionLogEntry({
582
- self: conflictedEntry,
583
- existing: await readLogEntry(this.#storage, logEntryKey),
584
- batchSize: inputs.length
585
- });
586
- if (decision.adopt) committedEntries = [decision.entry];
587
- else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; ${decision.reason}`);
588
- } else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; peer wrote our seq`);
589
- }
590
- const batchLogBytes = committedEntries.reduce((sum, e) => sum + encodeJsonBytes(e).byteLength, 0);
591
- const next = {
592
- ...current,
593
- next_seq: current.next_seq + inputs.length,
594
- tail_bytes: current.tail_bytes + batchLogBytes
595
- };
596
- if (next.next_seq - current.next_seq !== inputs.length) throw new BaerlyError("Internal", `${errorPrefix}: GC-cadence invariant violated — next_seq advanced by ${next.next_seq - current.next_seq} but ${inputs.length} input(s) were committed on ${this.#currentJsonKey}`);
597
- const nextBody = encodeJsonBytes(next);
598
- const putOpts = {
599
- ifMatch: baseEtag,
600
- contentType: APPLICATION_JSON
601
- };
602
- let result;
603
- try {
604
- result = await this.#storage.put(this.#currentJsonKey, nextBody, putOpts);
605
- } catch (error) {
606
- this.#observe429(error, inputs[0].collection);
607
- if (isPreconditionFailed(error)) {
608
- ctxMetrics().counter("db.r2.put.412_total", 1, {
609
- collection: inputs[0].collection,
610
- step: "current-json-cas"
611
- });
612
- throw new BaerlyError("Conflict", `${errorPrefix}: CAS conflict on ${this.#currentJsonKey}`);
430
+ const acc = rangeAcc.get(field) ?? {
431
+ loInclusive: false,
432
+ hiInclusive: false
433
+ };
434
+ const v = clause.value;
435
+ if (clause.op === "gte") {
436
+ if (acc.lo === void 0 || v > acc.lo) {
437
+ acc.lo = v;
438
+ acc.loInclusive = true;
439
+ } else if (v === acc.lo && !acc.loInclusive) {}
440
+ } else if (clause.op === "gt") {
441
+ if (acc.lo === void 0 || v > acc.lo) {
442
+ acc.lo = v;
443
+ acc.loInclusive = false;
444
+ } else if (v === acc.lo) acc.loInclusive = false;
445
+ } else if (clause.op === "lte") {
446
+ if (acc.hi === void 0 || v < acc.hi) {
447
+ acc.hi = v;
448
+ acc.hiInclusive = true;
449
+ }
450
+ } else if (clause.op === "lt") {
451
+ if (acc.hi === void 0 || v < acc.hi) {
452
+ acc.hi = v;
453
+ acc.hiInclusive = false;
454
+ } else if (v === acc.hi) acc.hiInclusive = false;
613
455
  }
614
- throw error;
615
- }
616
- const prevSeq = current.next_seq;
617
- const maint = getCurrentContext()?.maintenance;
618
- if (maint?.disabled !== true) {
619
- if (shouldFireMaintenance(next, prevSeq, maint?.options?.gcInterval ?? 4)) await (maint?.dispatch ?? dispatchInlineAwaited)(() => runBoundedMaintenance({
620
- storage: this.#storage,
621
- currentJsonKey: this.#currentJsonKey,
622
- prevSeq,
623
- ...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes }
624
- }, maint?.options).then(() => {}, () => {}));
625
- }
626
- const classAOps = contentPutCount + entries.length + indexClassA + 1;
627
- return {
628
- entries: committedEntries,
629
- currentEtag: result.etag,
630
- classAOps,
631
- expectedEpoch
632
- };
633
- }
634
- /**
635
- * Read the pre-image content body for a doc by walking the live
636
- * log backwards from `currentNextSeq` looking for the
637
- * most-recent I/U entry on this `(collection, docId)`. Returns
638
- * `undefined` when:
639
- *
640
- * - the doc's most-recent op was `D` (tombstone — no live body);
641
- * - no entry for this doc lives inside the visible log range
642
- * `[log_seq_start, currentNextSeq)` (a fresh-insert race or
643
- * the doc has been folded into the snapshot but is no longer
644
- * referenced).
645
- *
646
- * Used ONLY by the index-emission path on `U` / `D` to compute
647
- * the stale-key set. Bounded by `log_seq_start`: entries below
648
- * have been folded into the snapshot and may already be swept
649
- * off the bucket — a snapshot fold is the rebuild command's job
650
- * (see `./rebuild-index.ts`), not the writer's.
651
- *
652
- * **Cost note:** linear walk, O(snapshot lag). For day-one Phase
653
- * 8 collections (helpdesk-shape: 100s of docs, <10k log entries)
654
- * this is fine — the compactor folds the live tail every ~100
655
- * entries (`packages/server/src/compactor.ts`). A follow-up ticket
656
- * caches per-doc index head in `current.json` for O(1) lookup.
657
- * The bound is documented; out of scope here.
658
- */
659
- /**
660
- * Auto-create the per-collection `current.json` at
661
- * `this.#currentJsonKey` with a zero-state initial manifest. Called
662
- * by `#singleAttemptCommit` when the read returned `null` (fresh
663
- * bucket / fresh collection).
664
- *
665
- * Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
666
- * peer raced us and won, the storage layer surfaces `Conflict`; we
667
- * recover by re-reading the now-present manifest. We do NOT retry
668
- * the create — a single recover-via-read covers every race that
669
- * could have produced our null read.
670
- *
671
- * The seed shape (`snapshot: null`, `next_seq: 0`, `log_seq_start:
672
- * 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
673
- * matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
674
- * operator who pre-provisions and a writer who auto-creates land
675
- * on byte-identical bytes.
676
- *
677
- * @throws BaerlyError code="InvalidResponse" — the post-recover
678
- * re-read also returned null. Defensive guard; in practice
679
- * unreachable because the Conflict implies the key now exists.
680
- */
681
- async #provisionCurrentJson() {
682
- const initial = {
683
- schema_version: 2,
684
- snapshot: null,
685
- next_seq: 0,
686
- log_seq_start: 0,
687
- writer_fence: {
688
- epoch: 0,
689
- owner: "",
690
- claimed_at: ""
691
- },
692
- tail_bytes: 0,
693
- snapshot_bytes: 0,
694
- snapshot_rows: 0
695
- };
696
- try {
697
- return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
698
- } catch (error) {
699
- if (!(error instanceof BaerlyError) || error.code !== "Conflict") throw error;
456
+ rangeAcc.set(field, acc);
700
457
  }
701
- const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
702
- if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
703
- return recovered;
704
458
  }
705
- async #readPreImage(logPrefix, collection, docId, currentNextSeq) {
706
- for (let s = currentNextSeq - 1; s >= 0; s--) {
707
- const logKey = `${logPrefix}/log/${s}.json`;
708
- const got = await this.#storage.get(logKey);
709
- if (got === null) continue;
710
- let entry;
711
- try {
712
- entry = decodeJsonBytes(got.body);
713
- } catch {
459
+ for (const [field, acc] of rangeAcc) rangeOps.set(field, {
460
+ ...acc.lo !== void 0 ? { lo: acc.lo } : {},
461
+ ...acc.hi !== void 0 ? { hi: acc.hi } : {},
462
+ loInclusive: acc.loInclusive,
463
+ hiInclusive: acc.hiInclusive
464
+ });
465
+ if (equality.size === 0 && rangeOps.size === 0 && inOps.size === 0) return {
466
+ kind: "full-scan",
467
+ reason: "predicate-uses-operators-only"
468
+ };
469
+ const candidates = [];
470
+ for (let defIndex = 0; defIndex < indexes.length; defIndex++) {
471
+ const def = indexes[defIndex];
472
+ const tuple = typeof def.on === "string" ? [def.on] : def.on;
473
+ const equalityKeys = [];
474
+ let tail;
475
+ for (let i = 0; i < tuple.length; i++) {
476
+ const field = tuple[i];
477
+ const v = equality.get(field);
478
+ if (v !== void 0) {
479
+ equalityKeys.push(v);
714
480
  continue;
715
481
  }
716
- if (entry.collection !== collection || entry.doc_id !== docId) continue;
717
- if (entry.op === "D") return;
718
- if ((entry.op === "I" || entry.op === "U") && entry.after !== void 0) return entry.after;
482
+ const range = rangeOps.get(field);
483
+ if (range !== void 0) tail = {
484
+ kind: "range",
485
+ field,
486
+ info: range
487
+ };
488
+ else {
489
+ const inVals = inOps.get(field);
490
+ if (inVals !== void 0) tail = {
491
+ kind: "in",
492
+ field,
493
+ values: inVals
494
+ };
495
+ }
496
+ break;
719
497
  }
498
+ const candidateLen = equalityKeys.length + (tail !== void 0 ? 1 : 0);
499
+ if (candidateLen === 0) continue;
500
+ candidates.push({
501
+ def,
502
+ defIndex,
503
+ prefixLen: candidateLen,
504
+ equalityKeys,
505
+ ...tail !== void 0 ? { tail } : {}
506
+ });
720
507
  }
721
- /**
722
- * Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with
723
- * bounded parallelism via `walkLogRange`. Materialised entries are
724
- * discarded — the walk's only job is to surface a hole or a
725
- * malformed body inside the visible range as
726
- * `BaerlyError{code:"Internal"}` / `"InvalidResponse"`.
727
- *
728
- * Gated on `verifyLogIntegrityOnCommit`; default off in production
729
- * because the per-doc fold already lives in the read path. See the
730
- * option's docstring for the rationale and the opt-in convention.
731
- *
732
- * `logSeqStart` is the boundary set by the compactor on
733
- * `current.json.log_seq_start`. Entries below it have been folded
734
- * into the snapshot and may have been swept off the bucket, so the
735
- * walk MUST NOT GET-require them.
736
- */
737
- async #walkLog(logPrefix, logSeqStart, nextSeq) {
738
- await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);
739
- }
740
- /**
741
- * Bump the `db.r2.put.429_total` counter when `err` looks like an
742
- * R2 prefix-partition rate-limit. Best-effort: detected via
743
- * `BaerlyError{code:"NetworkError"}` with a `429` token in the
744
- * message. Called from every PUT call site's catch arm; mutually
745
- * exclusive in practice with `isPreconditionFailed` (412 ≠ 429).
746
- */
747
- #observe429(err, collection) {
748
- if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
749
- }
750
- /**
751
- * Emit the per-logical-write `class_a_ops_per_logical_write`
752
- * histogram shared by `commit` and `commitBatch`. `classAOps`
753
- * differs between the two paths (retry-budget vs batch shape),
754
- * so each caller computes it.
755
- */
756
- #emitWriteMetrics(collection, classAOps) {
757
- ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
758
- }
759
- /**
760
- * Re-read `current.json` after a successful CAS and assert the
761
- * writer-fence epoch is still ours. The CAS only mutated `next_seq`
762
- * (the fence is preserved from `current`), so a post-write epoch
763
- * mismatch can only mean another writer claimed the fence between
764
- * our step-1 read and step-6 PUT — the exact split-brain
765
- * `WriterFence` prevents. Throws `Conflict`; no retry, since the
766
- * stale writer must defer to the new authority.
767
- *
768
- * The fence-verify GET is Class B and intentionally NOT counted in
769
- * `class_a_ops_per_logical_write`.
770
- */
771
- async #verifyFenceUnchanged(expectedEpoch, where) {
772
- const postRead = await readCurrentJson(this.#storage, this.#currentJsonKey);
773
- if (postRead === null) return;
774
- if (postRead.json.writer_fence.epoch === expectedEpoch) return;
775
- throw new BaerlyError("Conflict", `${where}: writer fence bumped from epoch ${expectedEpoch} to ${postRead.json.writer_fence.epoch} during commit on ${this.#currentJsonKey}; stale writer aborting`);
776
- }
777
- /**
778
- * Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
779
- * at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
780
- * from re-racing in lockstep. Worst-case total wait across the
781
- * default 8 attempts is roughly 2.5 s — well under a typical
782
- * Worker request budget.
783
- */
784
- async #backoff(attempt) {
785
- const sleepMs = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS) * this.#random();
786
- if (sleepMs <= 0) return;
787
- await new Promise((r) => setTimeout(r, sleepMs));
508
+ if (candidates.length === 0) return {
509
+ kind: "full-scan",
510
+ reason: "no-matching-index"
511
+ };
512
+ const rank = (c) => {
513
+ if (c.def.predicate === void 0) return 1;
514
+ return predicateImplies(c.def.predicate, wire) ? 0 : 2;
515
+ };
516
+ candidates.sort((a, b) => {
517
+ const aRank = rank(a);
518
+ const bRank = rank(b);
519
+ if (aRank !== bRank) return aRank - bRank;
520
+ if (b.prefixLen !== a.prefixLen) return b.prefixLen - a.prefixLen;
521
+ return a.defIndex - b.defIndex;
522
+ });
523
+ const best = candidates[0];
524
+ if (best.tail !== void 0 && best.tail.kind === "in") {
525
+ if (best.tail.values.length > 50) return {
526
+ kind: "full-scan",
527
+ reason: "no-matching-index"
528
+ };
788
529
  }
789
- };
790
- /**
791
- * `true` when the underlying storage surfaced a `PreconditionFailed`
792
- * 412 (or its non-S3 equivalents). Every in-tree {@link Storage} impl
793
- * surfaces a lost CAS as `BaerlyError{code:"Conflict"}`.
794
- */
795
- const isPreconditionFailed = (err) => err instanceof BaerlyError && err.code === "Conflict";
796
- /**
797
- * `true` when the underlying storage surfaced an R2 prefix-partition
798
- * rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
799
- * onto `BaerlyError.cause` as `{ status }`; we discriminate on that
800
- * structured field rather than regex-matching the message.
801
- */
802
- const is429 = (err) => {
803
- if (!(err instanceof BaerlyError) || err.code !== "NetworkError") return false;
804
- return err.cause?.status === 429;
530
+ return {
531
+ kind: "index-walk",
532
+ indexName: best.def.name,
533
+ equalityKeys: best.equalityKeys,
534
+ ...best.tail !== void 0 && best.tail.kind === "range" ? { rangeOn: {
535
+ field: best.tail.field,
536
+ ...best.tail.info.lo !== void 0 ? { lo: best.tail.info.lo } : {},
537
+ ...best.tail.info.hi !== void 0 ? { hi: best.tail.info.hi } : {},
538
+ loInclusive: best.tail.info.loInclusive,
539
+ hiInclusive: best.tail.info.hiInclusive
540
+ } } : {},
541
+ ...best.tail !== void 0 && best.tail.kind === "in" ? { inOn: {
542
+ field: best.tail.field,
543
+ values: best.tail.values
544
+ } } : {}
545
+ };
805
546
  };
806
547
  //#endregion
807
- //#region packages/server/src/query-planner-implies.ts
548
+ //#region packages/server/src/schema.ts
808
549
  /**
809
- * Filtered-index implication checker — decides whether every
810
- * document accepted by a query predicate is also accepted by a
811
- * filtered index's predicate. The query planner uses the result to
812
- * rank candidate indexes; see {@link "./query-planner.ts".planQuery}.
550
+ * Schema-validator runtime helper for `Db.insert` / `Query.update` /
551
+ * `Collection.replace` boundary checks.
813
552
  *
814
- * Pure-function module: no I/O, no `Db` / `Storage` imports. Lives
815
- * in `@baerly/server` (not in `@baerly/protocol`) because the
816
- * planner is the only caller.
553
+ * The `SchemaValidator` / `SchemaIssue` TYPES live in
554
+ * `@baerly/protocol` (cross-platform). This module owns the runtime
555
+ * helper `validateOrThrow` that runs a validator and raises a
556
+ * `BaerlyError{code:"SchemaError"}` on failure.
817
557
  *
818
- * Operates on the wire form: both inputs are {@link PredicateWire}s
819
- * with clauses already grouped by `(op, field, value)`. The
820
- * normaliser at `@baerly/protocol`'s `./query/normalize.ts` has
821
- * already flattened nested literal sub-predicates into dotted-path
822
- * `eq` clauses, so there is no recursion on nested objects here.
558
+ * @example
559
+ * ```ts
560
+ * import { z } from "zod";
561
+ * import { defineConfig } from "@gusto/baerly-storage/config";
562
+ *
563
+ * const Ticket = z.object({
564
+ * _id: z.string(),
565
+ * status: z.enum(["open", "closed"]),
566
+ * title: z.string().min(1),
567
+ * });
568
+ *
569
+ * export default defineConfig({
570
+ * collections: {
571
+ * tickets: { schema: Ticket },
572
+ * },
573
+ * });
574
+ * ```
823
575
  */
824
576
  /**
825
- * Group a wire's clauses by `field` so the per-field implication
826
- * check can reason over one bundle at a time. Inlined small helper
827
- * (not exported) so the planner module doesn't need to expose its
828
- * grouping helper as a cross-module contract.
577
+ * Run a validator and throw `BaerlyError{code:"SchemaError"}` on failure.
578
+ * On success returns the validator's output (which for transforming
579
+ * validators may differ from the input).
580
+ *
581
+ * Field paths are normalised to `(string | number)[]` so the wire shape
582
+ * is JSON-clean. Symbol keys (rare; StandardSchemaV1 permits them) are
583
+ * coerced to `String(sym)` — we never emit `symbol` on the wire.
584
+ *
585
+ * The thrown error's `message` carries a one-line summary
586
+ * (`"<collection>.<verb>: <issuesCount> field(s) failed validation: <first>"`)
587
+ * for stderr-readable logs; the structured `issues` are on `.issues`.
829
588
  */
830
- const groupByField = (wire) => {
831
- const groups = /* @__PURE__ */ new Map();
832
- for (const clause of wire.clauses) {
833
- const bucket = groups.get(clause.field);
834
- if (bucket === void 0) groups.set(clause.field, [clause]);
835
- else bucket.push(clause);
836
- }
837
- return groups;
589
+ const validateOrThrow = async (schema, candidate, context) => {
590
+ const result = await schema["~standard"].validate(candidate);
591
+ if (result.issues === void 0) return result.value;
592
+ const issues = result.issues.map((i) => ({
593
+ path: (i.path ?? []).map((p) => {
594
+ const raw = typeof p === "object" && p !== null && "key" in p ? p.key : p;
595
+ return typeof raw === "number" ? raw : String(raw);
596
+ }),
597
+ message: i.message
598
+ }));
599
+ const first = issues[0];
600
+ const summary = first === void 0 ? "schema validation failed (no issues reported)" : `${first.path.length === 0 ? "<root>" : first.path.join(".")}: ${first.message}`;
601
+ throw new BaerlyError("SchemaError", `${context.collection}.${context.verb}: ${issues.length} field${issues.length === 1 ? "" : "s"} failed validation: ${summary}`, void 0, issues);
838
602
  };
603
+ //#endregion
604
+ //#region packages/server/src/key-limit.ts
605
+ const utf8 = new TextEncoder();
839
606
  /**
840
- * Collapse a per-field clause list into an {@link OperatorBundle}.
841
- * Returns `"unknown-shape"` when the group has more than one `in`
842
- * clause (set-intersection at plan time is out of scope) or
843
- * unrecognised ops slipping through (defensive — the validator
844
- * already locked the op vocabulary). Multiple `eq` clauses on one
845
- * field: the validator proves they all agree, so we pick the first.
846
- * Multiple range clauses on one field: take the strictest bound
847
- * (tightest `lo` = numerically largest; tightest `hi` = numerically
848
- * smallest).
607
+ * Reject an assembled object key over the S3/R2 full-key ceiling
608
+ * ({@link MAX_KEY_BYTES}) as `InvalidConfig`. Per-segment caps don't
609
+ * bound the sum, and index values skip `assertPathSegment` entirely, so
610
+ * this post-encoding check at the writer's PUT sites is their only
611
+ * overflow guard. @see docs/spec/storage-compatibility.md
849
612
  */
850
- const decodeGroup = (clauses) => {
851
- const bundle = {};
852
- for (const clause of clauses) {
853
- const v = clause.value;
854
- if (clause.op === "eq") bundle.eq = v;
855
- else if (clause.op === "gte") {
856
- const next = {
857
- value: v,
858
- inclusive: true
859
- };
860
- bundle.lo = tightestLo(bundle.lo, next);
861
- } else if (clause.op === "gt") {
862
- const next = {
863
- value: v,
864
- inclusive: false
865
- };
866
- bundle.lo = tightestLo(bundle.lo, next);
867
- } else if (clause.op === "lte") {
868
- const next = {
869
- value: v,
870
- inclusive: true
871
- };
872
- bundle.hi = tightestHi(bundle.hi, next);
873
- } else if (clause.op === "lt") {
874
- const next = {
875
- value: v,
876
- inclusive: false
877
- };
878
- bundle.hi = tightestHi(bundle.hi, next);
879
- } else if (clause.op === "in") {
880
- if (bundle.in !== void 0) return "unknown-shape";
881
- if (!Array.isArray(v)) return "unknown-shape";
882
- bundle.in = v;
883
- } else return "unknown-shape";
884
- }
885
- return bundle;
886
- };
887
- const tightestLo = (existing, next) => {
888
- if (existing === void 0) return next;
889
- if (typeof existing.value !== typeof next.value) return existing;
890
- if (next.value > existing.value) return next;
891
- if (next.value < existing.value) return existing;
892
- if (!next.inclusive && existing.inclusive) return next;
893
- return existing;
894
- };
895
- const tightestHi = (existing, next) => {
896
- if (existing === void 0) return next;
897
- if (typeof existing.value !== typeof next.value) return existing;
898
- if (next.value < existing.value) return next;
899
- if (next.value > existing.value) return existing;
900
- if (!next.inclusive && existing.inclusive) return next;
901
- return existing;
613
+ const assertKeyWithinLimit = (key) => {
614
+ const bytes = utf8.encode(key).length;
615
+ if (bytes > 1024) throw new BaerlyError("InvalidConfig", `object key exceeds ${MAX_KEY_BYTES} bytes (got ${bytes}): ${JSON.stringify(key.slice(0, 80))}…`);
902
616
  };
617
+ //#endregion
618
+ //#region packages/server/src/log-conflict-adoption.ts
903
619
  /**
904
- * Does the query's lower bound `loQ` (`undefined` if none) prove that
905
- * every matching doc satisfies the filter's lower bound `loF`?
620
+ * Decide whether the entry already at `/log/<seq>.json` is the
621
+ * writer's own prior in-flight attempt and may be adopted. Pure
622
+ * function; no I/O. The caller performs the GET (when the log PUT
623
+ * surfaces 412) and passes the read-back body in `ctx.existing`.
906
624
  *
907
- * `loF.inclusive` true → need doc ≥ loF.value; `loF.inclusive` false →
908
- * need doc > loF.value. A stricter `loQ` (numerically larger or with
909
- * tighter inclusivity) always implies a looser `loF`.
625
+ * ## Correctness precondition
626
+ *
627
+ * A fresh `session` id is minted per `commit()` call, seq-stable
628
+ * across that call's retries. Adoption compares the writer-minted
629
+ * intent/body fields as well as session and seq: a dropped-ack retry
630
+ * reuses the same attempted entry and adopts, while a same-session /
631
+ * same-seq occupant carrying a different logical mutation is treated as
632
+ * a conflict and skipped by the caller's forward-probe loop.
633
+ *
634
+ * @see {@link AdoptionDecision} for the return shape.
635
+ * @see The soundness invariant in this module's header docstring.
910
636
  */
911
- const lowerBoundImplies = (loF, loQ) => {
912
- if (loQ === void 0) return false;
913
- if (typeof loF.value !== typeof loQ.value) return false;
914
- if (loQ.value > loF.value) return true;
915
- if (loQ.value < loF.value) return false;
916
- if (loF.inclusive) return true;
917
- return !loQ.inclusive;
918
- };
919
- /** Mirror of lowerBoundImplies for upper bounds. */
920
- const upperBoundImplies = (hiF, hiQ) => {
921
- if (hiQ === void 0) return false;
922
- if (typeof hiF.value !== typeof hiQ.value) return false;
923
- if (hiQ.value < hiF.value) return true;
924
- if (hiQ.value > hiF.value) return false;
925
- if (hiF.inclusive) return true;
926
- return !hiQ.inclusive;
927
- };
928
- const loFromQuery = (q) => {
929
- if (q.eq !== void 0) return {
930
- value: q.eq,
931
- inclusive: true
637
+ const tryAdoptOwnSessionLogEntry = (ctx) => {
638
+ if (ctx.existing.session !== ctx.self.session) return {
639
+ adopt: false,
640
+ reason: "foreign-session"
932
641
  };
933
- if (q.in !== void 0 && q.in.length > 0) return {
934
- value: q.in.reduce((acc, v) => v < acc ? v : acc, q.in[0]),
935
- inclusive: true
642
+ if (ctx.existing.seq !== ctx.self.seq) return {
643
+ adopt: false,
644
+ reason: "wrong-seq"
936
645
  };
937
- return q.lo;
938
- };
939
- const hiFromQuery = (q) => {
940
- if (q.eq !== void 0) return {
941
- value: q.eq,
942
- inclusive: true
646
+ if (JSON.stringify(ctx.existing) !== JSON.stringify(ctx.self)) return {
647
+ adopt: false,
648
+ reason: "intent-mismatch"
943
649
  };
944
- if (q.in !== void 0 && q.in.length > 0) return {
945
- value: q.in.reduce((acc, v) => v > acc ? v : acc, q.in[0]),
946
- inclusive: true
650
+ return {
651
+ adopt: true,
652
+ entry: ctx.existing
947
653
  };
948
- return q.hi;
949
654
  };
655
+ //#endregion
656
+ //#region packages/server/src/writer.ts
950
657
  /**
951
- * Filtered-index implication checker — decides whether every document
952
- * accepted by `queryWire` is also accepted by `indexFilterWire`. When
953
- * `true`, a walk over an index declared with `predicate: indexFilterWire`
954
- * is **complete** for `queryWire`: no matching doc is missing
955
- * from the smaller key set, so the planner can prefer it.
956
- *
957
- * Implication on `eq`, `gt` / `gte`, `lt` / `lte`, and `in` is
958
- * sound and complete in pure operator form; combined shapes (e.g.
959
- * range-on-filter and `in`-on-query) follow the algebra in the body
960
- * JSDoc.
961
- *
962
- * Algorithm — group both wires by `field`, then for every field
963
- * present in `indexFilterWire`:
964
- *
965
- * 1. Decode the filter's clause group into an {@link OperatorBundle}.
966
- * "unknown-shape" → refuse implication conservatively.
967
- * 2. The query MUST have at least one clause on that field —
968
- * otherwise the query says nothing about that field and cannot
969
- * possibly imply the filter's constraint.
970
- * 3. Decode the query's clause group on the same field.
971
- * 4. For each non-empty slot of the filter bundle, the query bundle
972
- * must establish the constraint:
973
- * - `eq` → query establishes equality (via its own `eq`).
974
- * - `in` → query is contained in the set (via `eq` ∈ set or
975
- * `in` ⊆ set).
976
- * - `lo` / `hi` → query establishes the bound via `eq`, `in`
977
- * (then min/max of the set), or its own `lo`/`hi` with the
978
- * inclusivity rules in {@link lowerBoundImplies} /
979
- * {@link upperBoundImplies}.
980
- * Mixed types (e.g. number filter vs string query) refuse
981
- * implication conservatively.
658
+ * `Writer` — stateless multi-instance write engine (single-write commit).
659
+ *
660
+ * Each {@link Writer.commit} reads `current.json` FRESH (for
661
+ * `log_seq_start` / `tail_hint` as a probe FLOOR — a lower bound, NOT a
662
+ * CAS precondition), PUTs the content body, then **creates `log/<seq>`
663
+ * via `If-None-Match: "*"`. That create IS the commit / linearization
664
+ * point.** The writer writes NOTHING to `current.json` on the commit
665
+ * path; `tail_hint` advances outside ordinary commits via compaction
666
+ * folds, write-tick refreshes, and explicit operator/import paths. The
667
+ * commit model and its invariants are recorded in ADR-004
668
+ * (`docs/adr/004-single-write-commit.md`). The
669
+ * optional integrity walk is gated by
670
+ * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off).
671
+ *
672
+ * No per-write cache: every commit re-reads + re-probes, so N stateless
673
+ * instances contend at one place — the `If-None-Match` create of
674
+ * `log/<seq>`. The loser gets a 412 and re-probes forward to the next
675
+ * empty slot. A 412 from the writer's OWN session at the same seq is its
676
+ * own lost-ack / crashed-but-durable commit → adopted (not retried), so
677
+ * the write lands at EXACTLY `seq`, never duplicated.
678
+ *
679
+ * **Crash safety.** Order is content + additive index `newKeys` →
680
+ * `log/<seq>` create → stale index-key DELETEs. A crash before the
681
+ * create leaves an unreferenced content body + orphan additive index
682
+ * keys (no log entry references them), not an orphan log entry with
683
+ * missing content — the compactor sweeps the content, and a stray
684
+ * additive key only ever yields a false-POSITIVE candidate that
685
+ * `matchesWire` (read path) drops. Emitting `newKeys` before the commit
686
+ * means a committed row is ALWAYS index-findable; the stale-key DELETE
687
+ * stays after the commit so a crash can never de-index a committed
688
+ * doc. See `index-emit-order.test.ts` and ADR-004 Q4.
982
689
  *
983
- * Returns `true` iff every clause was satisfied. An empty
984
- * `indexFilterWire` is vacuously implied by any `queryWire`.
690
+ * **`LogEntry` shape.** Emitted entries follow the contract in
691
+ * `packages/protocol/src/log.ts` (see {@link LogEntry}) and
692
+ * `docs/spec/log-entry-shape.md`. The on-bucket key is
693
+ * `log/<seq>.json` (the integer `seq` is the load-bearing
694
+ * identifier; the `lsn` string is schema-only).
985
695
  *
986
- * Soundness contract — when this function returns `true`,
987
- * `matchesWire(queryWire, doc) ⇒ matchesWire(indexFilterWire, doc)` for
988
- * any document `doc`. Tests pin this property; see
989
- * `./query-planner-implies.test.ts`.
696
+ * @see docs/spec/sync-protocol.md for the protocol invariants this
697
+ * loop preserves.
698
+ * @see docs/spec/log-entry-shape.md for the per-field contract.
990
699
  */
991
- const predicateImplies = (indexFilterWire, queryWire) => {
992
- const filterGroups = groupByField(indexFilterWire);
993
- const queryGroups = groupByField(queryWire);
994
- for (const [field, filterClauses] of filterGroups) {
995
- const filterBundle = decodeGroup(filterClauses);
996
- if (filterBundle === "unknown-shape") return false;
997
- const queryClauses = queryGroups.get(field);
998
- if (queryClauses === void 0) return false;
999
- const queryBundle = decodeGroup(queryClauses);
1000
- if (queryBundle === "unknown-shape") return false;
1001
- if (filterBundle.eq !== void 0) {
1002
- if (queryBundle.eq === void 0) return false;
1003
- if (!deepEqualDocumentValue(queryBundle.eq, filterBundle.eq)) return false;
1004
- continue;
1005
- }
1006
- if (filterBundle.in !== void 0) {
1007
- const set = filterBundle.in;
1008
- const contains = (v) => set.some((m) => deepEqualDocumentValue(m, v));
1009
- if (queryBundle.eq !== void 0) {
1010
- if (!contains(queryBundle.eq)) return false;
1011
- } else if (queryBundle.in !== void 0) {
1012
- for (const v of queryBundle.in) if (!contains(v)) return false;
1013
- } else return false;
1014
- continue;
1015
- }
1016
- if (filterBundle.lo !== void 0) {
1017
- if (!lowerBoundImplies(filterBundle.lo, loFromQuery(queryBundle))) return false;
1018
- }
1019
- if (filterBundle.hi !== void 0) {
1020
- if (!upperBoundImplies(filterBundle.hi, hiFromQuery(queryBundle))) return false;
1021
- }
1022
- }
1023
- return true;
1024
- };
700
+ const CAS_CONFLICT_RESOLUTION = "Re-read and retry.";
701
+ const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
702
+ const DEFAULT_INITIAL_BACKOFF_MS = 25;
703
+ const MAX_BACKOFF_MS = 1500;
704
+ const APPLICATION_JSON = "application/json";
705
+ /**
706
+ * Empty body for index entries. Each index entry is a fact ("doc
707
+ * `<docId>` has `<field> = <value>`"), not data — readers list the
708
+ * prefix, extract the doc id, then GET the content body separately.
709
+ * Pre-allocated module-level constant so every index PUT shares one
710
+ * zero-length buffer.
711
+ */
712
+ const EMPTY_BODY = /* @__PURE__ */ new Uint8Array(0);
1025
713
  /**
1026
- * Choose a query plan over the wire predicate + declared indexes.
1027
- * Pure function. The executor enforces the I/O semantics; the
1028
- * planner's only contract is "given these inputs, this is the
1029
- * routing decision."
714
+ * Stateless write engine for the multi-instance core.
1030
715
  *
1031
- * Algorithm:
1032
- * 1. `wire === undefined` or empty → `no-predicate`.
1033
- * 2. `indexes.length === 0` → `no-indexes-declared`.
1034
- * 3. Partition wire clauses per field into:
1035
- * - `equality[f] = v` from `eq` clauses.
1036
- * - `rangeOps[f] = {lo, hi, loInclusive, hiInclusive}` from
1037
- * one or more of `gt`/`gte`/`lt`/`lte` clauses on `f`.
1038
- * - `inOps[f] = [...]` from a single `in` clause on `f`.
1039
- * - Defensive: any field whose clause group mixes op-channels
1040
- * (mostly impossible post-validation) is marked unroutable
1041
- * and skipped — the executor's full-wire `matchesWire(...)`
1042
- * post-fetch catches the residue automatically.
1043
- * 4. If no equality / range / `in` candidates exist →
1044
- * `predicate-uses-operators-only`.
1045
- * 5. For each `def`, walk `def.on` left-to-right consuming
1046
- * equality clauses for each indexed field. On the FIRST field
1047
- * where the equality clause is absent, check whether a range
1048
- * or `in` clause is available for that field — if so, that's
1049
- * the "tail slot" of the walk.
1050
- * 6. Score candidates by `(equalityPrefixLen, hasTailExtension)`.
1051
- * Longest prefix wins; tail-extension breaks ties. If no
1052
- * candidate consumed at least one field (equality OR
1053
- * range/`in`): `no-matching-index`.
1054
- * 7. `in` FAN-OUT GUARD: if the chosen plan's `in` slot has
1055
- * `values.length > IN_FANOUT_THRESHOLD`, fall back to
1056
- * `FullScanPlan{reason:"no-matching-index"}` — N sequential
1057
- * LISTs cost more than a snapshot+log fold.
716
+ * Construction is cheap and performs zero I/O — adapters build a
717
+ * fresh `Writer` per request and discard it. All real work
718
+ * happens in {@link commit}.
1058
719
  *
1059
- * The planner deliberately treats `def.on` as the LITERAL tuple of
1060
- * field names — top-level only. Dotted paths are out of scope here
1061
- * (the projector at `indexes.ts:projectIndexValues` is top-level-
1062
- * only too).
720
+ * @example
721
+ * ```ts
722
+ * import { Writer } from "@gusto/baerly-storage";
723
+ * import { MemoryStorage } from "@gusto/baerly-storage";
1063
724
  *
1064
- * **Range/`in` is allowed only on the LAST indexed field beyond the
1065
- * equality prefix** — on a composite `[a, b]`, a range on `a` with
1066
- * equality on `b` is NOT contiguous under the key encoding (the `b`
1067
- * slot sits to the right of the varying `a` slot). Clauses landing
1068
- * outside the tail slot are simply left for the executor's full-
1069
- * predicate re-check.
725
+ * const writer = new Writer({
726
+ * storage: new MemoryStorage(),
727
+ * currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
728
+ * });
729
+ *
730
+ * const result = await writer.commit({
731
+ * op: "I",
732
+ * collection: "tickets",
733
+ * docId: "doc-1",
734
+ * body: { _id: "doc-1", title: "hello" },
735
+ * });
736
+ * console.log(result.entry.seq, result.attempts);
737
+ * ```
1070
738
  */
1071
- const planQuery = (wire, indexes) => {
1072
- if (wire === void 0 || wire.clauses.length === 0) return {
1073
- kind: "full-scan",
1074
- reason: "no-predicate"
1075
- };
1076
- if (indexes.length === 0) return {
1077
- kind: "full-scan",
1078
- reason: "no-indexes-declared"
1079
- };
1080
- const equality = /* @__PURE__ */ new Map();
1081
- const rangeOps = /* @__PURE__ */ new Map();
1082
- const inOps = /* @__PURE__ */ new Map();
1083
- const unroutable = /* @__PURE__ */ new Set();
1084
- const rangeAcc = /* @__PURE__ */ new Map();
1085
- for (const clause of wire.clauses) {
1086
- const field = clause.field;
1087
- if (unroutable.has(field)) continue;
1088
- if (clause.op === "eq") {
1089
- if (inOps.has(field) || rangeAcc.has(field)) {
1090
- unroutable.add(field);
1091
- equality.delete(field);
1092
- inOps.delete(field);
1093
- rangeAcc.delete(field);
739
+ var Writer = class {
740
+ #storage;
741
+ #currentJsonKey;
742
+ #maxRetries;
743
+ #initialBackoffMs;
744
+ #random;
745
+ #indexes;
746
+ #verifyLogIntegrityOnCommit;
747
+ constructor(opts) {
748
+ this.#storage = opts.storage;
749
+ this.#currentJsonKey = opts.currentJsonKey;
750
+ this.#maxRetries = opts.options?.maxRetries ?? 8;
751
+ this.#initialBackoffMs = opts.options?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
752
+ this.#random = opts.options?.random ?? Math.random;
753
+ const indexes = opts.options?.indexes ?? [];
754
+ for (const def of indexes) validateIndexDefinition(def);
755
+ this.#indexes = indexes;
756
+ this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
757
+ }
758
+ /**
759
+ * Atomically commit one mutation. Reads `current.json` fresh (as a
760
+ * probe FLOOR, not a CAS precondition), PUTs the content body and any
761
+ * additive index `newKeys`, then creates `log/<seq>` via
762
+ * `If-None-Match: "*"` — that create IS the commit (single-write
763
+ * commit; no `current.json` CAS follows it). Stale index keys are
764
+ * DELETE'd after the commit.
765
+ *
766
+ * The hot-path cost under no contention on an unindexed collection is
767
+ * 1 GET + 2 PUTs (content + the committing `log/<seq>` create); each
768
+ * declared index that projects a key on this write adds one PUT
769
+ * (new key, before the commit) and, on U/D, up to one DELETE (stale
770
+ * key, after the commit). An in-flight peer write costs one extra GET
771
+ * + the backoff sleep per retry.
772
+ *
773
+ * Idempotency: PUT content uses `If-None-Match: "*"`, so a retry of
774
+ * the same logical write produces the same content key and the
775
+ * second PUT no-ops. The `log/<seq>` create also uses
776
+ * `If-None-Match: "*"`, so two writers racing the same tail cause
777
+ * exactly one create to win; the loser reads back the occupant,
778
+ * adopts its own lost-ack write or re-probes forward to the next
779
+ * empty slot.
780
+ *
781
+ * @throws BaerlyError code="Conflict" when a retryable conflict
782
+ * escapes the single-attempt helper and exhausts the retry budget
783
+ * (presently unreachable on the log-create 412 path).
784
+ * @throws BaerlyError code="Internal" when a log entry expected in
785
+ * `[0, tail_hint)` is missing — a protocol-invariant violation
786
+ * (compactor bug or stale `current.json`).
787
+ * @throws BaerlyError code="InvalidResponse" when a log-entry body
788
+ * isn't valid JSON.
789
+ *
790
+ * **Implicit provisioning.** When `current.json` does not exist at
791
+ * `currentJsonKey` (fresh bucket, fresh collection), the writer
792
+ * auto-creates it with a zero-state manifest before the commit
793
+ * lands. The cost is one extra Class A PUT on the very first
794
+ * commit per collection; steady-state cost is unchanged. A peer
795
+ * racing the same first-write loses cleanly on the create CAS
796
+ * and re-reads to pick up the winner's manifest.
797
+ */
798
+ async commit(input) {
799
+ assertDocId(input.docId);
800
+ const session = uuid().slice(0, 6);
801
+ const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
802
+ for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {
803
+ let success;
804
+ try {
805
+ success = await this.#singleAttemptCommit(input, session, logPrefix, "Writer");
806
+ } catch (error) {
807
+ if (!isPreconditionFailed(error)) throw error;
808
+ await this.#backoff(attempt);
1094
809
  continue;
1095
810
  }
1096
- equality.set(field, clause.value);
1097
- } else if (clause.op === "in") {
1098
- if (equality.has(field) || rangeAcc.has(field) || inOps.has(field)) {
1099
- unroutable.add(field);
1100
- equality.delete(field);
1101
- inOps.delete(field);
1102
- rangeAcc.delete(field);
1103
- continue;
811
+ this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));
812
+ return {
813
+ entry: success.entries[0],
814
+ currentEtag: success.currentEtag,
815
+ attempts: attempt
816
+ };
817
+ }
818
+ throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`, void 0, void 0, void 0, CAS_CONFLICT_RESOLUTION, true);
819
+ }
820
+ /**
821
+ * One full commit attempt — the body of {@link commit}. Reads
822
+ * `current.json`, PUTs content + additive index `newKeys` in parallel,
823
+ * then forward-probes the tail and creates `log/<seq>` once via
824
+ * `If-None-Match: "*"` — the numbered log create IS the commit
825
+ * (single-write commit; no `current.json` CAS follows it). Stale index
826
+ * keys are DELETE'd after the commit. Returns the success payload.
827
+ *
828
+ * Commits exactly one {@link CommitInput} — the numbered log create is
829
+ * the single linearization point per call.
830
+ *
831
+ * A log-create 412 is disambiguated by session read-back: own session
832
+ * / own seq ⇒ our crashed-or-lost-ack commit is already durable ⇒
833
+ * adopt; foreign session ⇒ re-probe forward and retry at the next
834
+ * empty slot. Thrown `BaerlyError`s (Internal, InvalidResponse,
835
+ * NetworkError) propagate.
836
+ *
837
+ * Crash safety invariant: content + additive index `newKeys` PUTs are
838
+ * awaited before the log create. A crash before the create leaves
839
+ * orphan content + additive index keys (no log entry references them)
840
+ * — the compactor sweeps the content, and a stray additive key only
841
+ * yields a false-positive candidate that `matchesWire` drops. A crash
842
+ * AFTER the create is a durable, committed write at `seq` whose index
843
+ * `newKeys` are already present (so it's index-findable); the only
844
+ * residual is a possibly-undeleted stale OLD-value key, dropped by
845
+ * `matchesWire` and cleaned by a later write / `rebuild-index`. The
846
+ * inverse — committed log entry with missing content, or a de-indexed
847
+ * committed doc — is never produced.
848
+ */
849
+ async #singleAttemptCommit(input, session, logPrefix, errorPrefix) {
850
+ const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
851
+ const current = read.json;
852
+ const baseEtag = read.etag;
853
+ if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.tail_hint);
854
+ const probeFloor = Math.max(logSeqStartOf(current), current.tail_hint);
855
+ const preCommitTail = await findLogTail(this.#storage, logPrefix, probeFloor);
856
+ let seq = preCommitTail;
857
+ const commitNowMs = Date.now();
858
+ const commitTs = new Date(commitNowMs).toISOString();
859
+ const lsnTimestamp = timestamp(commitNowMs);
860
+ const mintEntry = (atSeq) => ({
861
+ lsn: `${lsnTimestamp}_${session}_${countKey(atSeq)}`,
862
+ commit_ts: commitTs,
863
+ op: input.op,
864
+ collection: input.collection,
865
+ doc_id: input.docId,
866
+ session,
867
+ seq: atSeq,
868
+ ...input.op !== "D" && input.body !== void 0 ? { after: input.body } : {},
869
+ ...input.origin !== void 0 ? { origin: input.origin } : {}
870
+ });
871
+ let entry = mintEntry(seq);
872
+ let contentPutCount = 0;
873
+ let newKeysClassA = 0;
874
+ const parallelPuts = [];
875
+ if (input.op !== "D" && input.body !== void 0) {
876
+ contentPutCount++;
877
+ const bytes = encodeJsonBytes(input.body);
878
+ const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
879
+ assertKeyWithinLimit(contentKey);
880
+ parallelPuts.push(this.#storage.put(contentKey, bytes, {
881
+ ifNoneMatch: "*",
882
+ contentType: APPLICATION_JSON
883
+ }).catch((error) => {
884
+ this.#observe429(error, input.collection);
885
+ if (isPreconditionFailed(error)) return;
886
+ throw error;
887
+ }));
888
+ }
889
+ if (this.#indexes.length > 0 && input.op !== "D") {
890
+ const newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
891
+ for (const k of newKeys) {
892
+ assertKeyWithinLimit(k);
893
+ newKeysClassA++;
894
+ parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
895
+ ifNoneMatch: "*",
896
+ contentType: APPLICATION_JSON
897
+ }).catch((error) => {
898
+ this.#observe429(error, input.collection);
899
+ if (isPreconditionFailed(error)) return;
900
+ throw error;
901
+ }));
1104
902
  }
1105
- if (!Array.isArray(clause.value)) {
1106
- unroutable.add(field);
1107
- continue;
903
+ }
904
+ await Promise.all(parallelPuts);
905
+ let committedEntry = entry;
906
+ let probes = 0;
907
+ let transientRetries = 0;
908
+ for (;;) {
909
+ const logEntryKey = logObjectKey(logPrefix, seq);
910
+ assertKeyWithinLimit(logEntryKey);
911
+ let conflicted = false;
912
+ try {
913
+ await this.#storage.put(logEntryKey, encodeJsonBytes(entry), {
914
+ ifNoneMatch: "*",
915
+ contentType: APPLICATION_JSON
916
+ });
917
+ } catch (error) {
918
+ this.#observe429(error, entry.collection);
919
+ if (isPreconditionFailed(error)) {
920
+ ctxMetrics().counter("db.r2.put.412_total", 1, {
921
+ collection: entry.collection,
922
+ step: "log-put"
923
+ });
924
+ conflicted = true;
925
+ } else if (isTransientWrite(error) && transientRetries < this.#maxRetries) {
926
+ transientRetries++;
927
+ await this.#backoff(transientRetries);
928
+ continue;
929
+ } else throw error;
1108
930
  }
1109
- inOps.set(field, clause.value);
1110
- } else {
1111
- if (equality.has(field) || inOps.has(field)) {
1112
- unroutable.add(field);
1113
- equality.delete(field);
1114
- inOps.delete(field);
1115
- rangeAcc.delete(field);
1116
- continue;
931
+ if (!conflicted) {
932
+ committedEntry = entry;
933
+ break;
1117
934
  }
1118
- const acc = rangeAcc.get(field) ?? {
1119
- loInclusive: false,
1120
- hiInclusive: false
1121
- };
1122
- const v = clause.value;
1123
- if (clause.op === "gte") {
1124
- if (acc.lo === void 0 || v > acc.lo) {
1125
- acc.lo = v;
1126
- acc.loInclusive = true;
1127
- } else if (v === acc.lo && !acc.loInclusive) {}
1128
- } else if (clause.op === "gt") {
1129
- if (acc.lo === void 0 || v > acc.lo) {
1130
- acc.lo = v;
1131
- acc.loInclusive = false;
1132
- } else if (v === acc.lo) acc.loInclusive = false;
1133
- } else if (clause.op === "lte") {
1134
- if (acc.hi === void 0 || v < acc.hi) {
1135
- acc.hi = v;
1136
- acc.hiInclusive = true;
1137
- }
1138
- } else if (clause.op === "lt") {
1139
- if (acc.hi === void 0 || v < acc.hi) {
1140
- acc.hi = v;
1141
- acc.hiInclusive = false;
1142
- } else if (v === acc.hi) acc.hiInclusive = false;
935
+ const existing = await readLogEntry(this.#storage, logEntryKey);
936
+ const decision = tryAdoptOwnSessionLogEntry({
937
+ self: entry,
938
+ existing
939
+ });
940
+ if (decision.adopt) {
941
+ committedEntry = decision.entry;
942
+ break;
943
+ }
944
+ if (++probes > 1e5) throw new BaerlyError("Internal", `${errorPrefix}: log-tail forward-probe exceeded ${LOG_FORWARD_PROBE_CAP} on ${this.#currentJsonKey}`);
945
+ seq = await findLogTail(this.#storage, logPrefix, seq + 1);
946
+ entry = mintEntry(seq);
947
+ }
948
+ const committedEntries = [committedEntry];
949
+ const staleKeysClassA = await this.#cleanupStaleIndexKeysBestEffort({
950
+ input,
951
+ logPrefix,
952
+ seq
953
+ });
954
+ const indexClassA = newKeysClassA + staleKeysClassA;
955
+ if (this.#indexes.length > 0 && indexClassA > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", indexClassA, { collection: input.collection });
956
+ const prevSeq = preCommitTail;
957
+ const observedTail = seq + 1;
958
+ const maint = getCurrentContext()?.maintenance;
959
+ const gcInterval = maint?.options?.profile?.gcInterval ?? MAINTENANCE_PROFILE_CF_FREE.gcInterval;
960
+ if (maint?.disabled === true ? observedTail - current.tail_hint >= 128 : shouldFireMaintenance(current, prevSeq, gcInterval, observedTail)) await (maint?.dispatch ?? dispatchInlineAwaited)(() => runBoundedMaintenance({
961
+ storage: this.#storage,
962
+ currentJsonKey: this.#currentJsonKey,
963
+ prevSeq,
964
+ observedTail,
965
+ ...maint?.disabled === true && { disabled: true },
966
+ ...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes }
967
+ }, maint?.options).then(() => {}, () => {}));
968
+ return {
969
+ entries: committedEntries,
970
+ currentEtag: baseEtag,
971
+ classAOps: contentPutCount + 1 + indexClassA
972
+ };
973
+ }
974
+ /**
975
+ * Auto-create the per-collection `current.json` at
976
+ * `this.#currentJsonKey` with a zero-state initial manifest. Called
977
+ * by `#singleAttemptCommit` when the read returned `null` (fresh
978
+ * bucket / fresh collection).
979
+ *
980
+ * Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
981
+ * peer raced us and won, the storage layer surfaces `Conflict`; we
982
+ * recover by re-reading the now-present manifest. We do NOT retry
983
+ * the create — a single recover-via-read covers every race that
984
+ * could have produced our null read.
985
+ *
986
+ * The seed shape (`snapshot: null`, `tail_hint: 0`, `log_seq_start:
987
+ * 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
988
+ * matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
989
+ * operator who pre-provisions and a writer who auto-creates land
990
+ * on byte-identical bytes.
991
+ *
992
+ * @throws BaerlyError code="InvalidResponse" — the post-recover
993
+ * re-read also returned null. Defensive guard; in practice
994
+ * unreachable because the Conflict implies the key now exists.
995
+ */
996
+ async #provisionCurrentJson() {
997
+ const initial = {
998
+ schema_version: 3,
999
+ snapshot: null,
1000
+ tail_hint: 0,
1001
+ log_seq_start: 0,
1002
+ writer_fence: {
1003
+ epoch: 0,
1004
+ owner: "",
1005
+ claimed_at: ""
1006
+ },
1007
+ snapshot_bytes: 0,
1008
+ snapshot_rows: 0
1009
+ };
1010
+ try {
1011
+ return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
1012
+ } catch (error) {
1013
+ if (!(error instanceof BaerlyError) || error.code !== "Conflict") throw error;
1014
+ }
1015
+ const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
1016
+ if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
1017
+ return recovered;
1018
+ }
1019
+ async #cleanupStaleIndexKeysBestEffort(args) {
1020
+ if (this.#indexes.length === 0) return 0;
1021
+ const { input } = args;
1022
+ let staleKeys = [];
1023
+ try {
1024
+ if (input.op === "U") {
1025
+ const preImage = await this.#readPreImage(args.logPrefix, input.collection, input.docId, args.seq);
1026
+ const oldKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);
1027
+ const newSet = new Set(allIndexKeysFor(args.logPrefix, this.#indexes, input.body, input.docId));
1028
+ staleKeys = oldKeys.filter((k) => !newSet.has(k));
1029
+ } else if (input.op === "D") {
1030
+ const preImage = await this.#readPreImage(args.logPrefix, input.collection, input.docId, args.seq);
1031
+ staleKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);
1143
1032
  }
1144
- rangeAcc.set(field, acc);
1033
+ } catch {
1034
+ ctxMetrics().counter("db.write.index_cleanup_errors_total", 1, {
1035
+ collection: input.collection,
1036
+ step: "pre-image-read"
1037
+ });
1038
+ return 0;
1145
1039
  }
1040
+ const indexDeletes = [];
1041
+ for (const k of staleKeys) indexDeletes.push(this.#storage.delete(k).catch(() => {
1042
+ ctxMetrics().counter("db.write.index_cleanup_errors_total", 1, {
1043
+ collection: input.collection,
1044
+ step: "delete"
1045
+ });
1046
+ }));
1047
+ await Promise.all(indexDeletes);
1048
+ return staleKeys.length;
1146
1049
  }
1147
- for (const [field, acc] of rangeAcc) rangeOps.set(field, {
1148
- ...acc.lo !== void 0 ? { lo: acc.lo } : {},
1149
- ...acc.hi !== void 0 ? { hi: acc.hi } : {},
1150
- loInclusive: acc.loInclusive,
1151
- hiInclusive: acc.hiInclusive
1152
- });
1153
- if (equality.size === 0 && rangeOps.size === 0 && inOps.size === 0) return {
1154
- kind: "full-scan",
1155
- reason: "predicate-uses-operators-only"
1156
- };
1157
- const candidates = [];
1158
- for (let defIndex = 0; defIndex < indexes.length; defIndex++) {
1159
- const def = indexes[defIndex];
1160
- const tuple = typeof def.on === "string" ? [def.on] : def.on;
1161
- const equalityKeys = [];
1162
- let tail;
1163
- for (let i = 0; i < tuple.length; i++) {
1164
- const field = tuple[i];
1165
- const v = equality.get(field);
1166
- if (v !== void 0) {
1167
- equalityKeys.push(v);
1050
+ /**
1051
+ * Read the pre-image content body for a doc by walking the live log
1052
+ * backwards from `currentNextSeq` looking for the most-recent I/U
1053
+ * entry on this `(collection, docId)`. Returns `undefined` when:
1054
+ *
1055
+ * - the doc's most-recent op was `D` (tombstone — no live body);
1056
+ * - no entry for this doc lives inside the visible log range
1057
+ * `[log_seq_start, currentNextSeq)` (a fresh-insert race or the
1058
+ * doc has been folded into the snapshot but is no longer
1059
+ * referenced).
1060
+ *
1061
+ * Used ONLY by the index-emission path's stale-key half (Step 5b, on
1062
+ * `U` / `D`) to compute which OLD-value keys to DELETE. Bounded by
1063
+ * `log_seq_start`: entries below have been folded into the snapshot
1064
+ * and may already be swept off the bucket — a snapshot fold is the
1065
+ * rebuild command's job (see `./rebuild-index.ts`), not the writer's.
1066
+ *
1067
+ * **Cost note:** linear walk, O(snapshot lag). For helpdesk-shape
1068
+ * collections (100s of docs, <10k log entries) this is fine — the
1069
+ * compactor folds the live tail every ~100 entries
1070
+ * (`packages/server/src/compactor.ts`). A follow-up ticket caches
1071
+ * per-doc index head in `current.json` for O(1) lookup.
1072
+ */
1073
+ async #readPreImage(logPrefix, collection, docId, currentNextSeq) {
1074
+ for (let s = currentNextSeq - 1; s >= 0; s--) {
1075
+ const logKey = logObjectKey(logPrefix, s);
1076
+ const got = await this.#storage.get(logKey);
1077
+ if (got === null) continue;
1078
+ let entry;
1079
+ try {
1080
+ entry = decodeJsonBytes(got.body);
1081
+ } catch {
1168
1082
  continue;
1169
1083
  }
1170
- const range = rangeOps.get(field);
1171
- if (range !== void 0) tail = {
1172
- kind: "range",
1173
- field,
1174
- info: range
1175
- };
1176
- else {
1177
- const inVals = inOps.get(field);
1178
- if (inVals !== void 0) tail = {
1179
- kind: "in",
1180
- field,
1181
- values: inVals
1182
- };
1183
- }
1184
- break;
1084
+ if (entry.collection !== collection || entry.doc_id !== docId) continue;
1085
+ if (entry.op === "D") return;
1086
+ if ((entry.op === "I" || entry.op === "U") && entry.after !== void 0) return entry.after;
1185
1087
  }
1186
- const candidateLen = equalityKeys.length + (tail !== void 0 ? 1 : 0);
1187
- if (candidateLen === 0) continue;
1188
- candidates.push({
1189
- def,
1190
- defIndex,
1191
- prefixLen: candidateLen,
1192
- equalityKeys,
1193
- ...tail !== void 0 ? { tail } : {}
1194
- });
1195
1088
  }
1196
- if (candidates.length === 0) return {
1197
- kind: "full-scan",
1198
- reason: "no-matching-index"
1199
- };
1200
- const rank = (c) => {
1201
- if (c.def.predicate === void 0) return 1;
1202
- return predicateImplies(c.def.predicate, wire) ? 0 : 2;
1203
- };
1204
- candidates.sort((a, b) => {
1205
- const aRank = rank(a);
1206
- const bRank = rank(b);
1207
- if (aRank !== bRank) return aRank - bRank;
1208
- if (b.prefixLen !== a.prefixLen) return b.prefixLen - a.prefixLen;
1209
- return a.defIndex - b.defIndex;
1210
- });
1211
- const best = candidates[0];
1212
- if (best.tail !== void 0 && best.tail.kind === "in") {
1213
- if (best.tail.values.length > 50) return {
1214
- kind: "full-scan",
1215
- reason: "no-matching-index"
1216
- };
1089
+ /**
1090
+ * Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with
1091
+ * bounded parallelism via `walkLogRange`. Materialised entries are
1092
+ * discarded — the walk's only job is to surface a hole or a
1093
+ * malformed body inside the visible range as
1094
+ * `BaerlyError{code:"Internal"}` / `"InvalidResponse"`.
1095
+ *
1096
+ * Gated on `verifyLogIntegrityOnCommit`; default off in production
1097
+ * because the per-doc fold already lives in the read path. See the
1098
+ * option's docstring for the rationale and the opt-in convention.
1099
+ *
1100
+ * `logSeqStart` is the boundary set by the compactor on
1101
+ * `current.json.log_seq_start`. Entries below it have been folded
1102
+ * into the snapshot and may have been swept off the bucket, so the
1103
+ * walk MUST NOT GET-require them.
1104
+ */
1105
+ async #walkLog(logPrefix, logSeqStart, nextSeq) {
1106
+ await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);
1107
+ }
1108
+ /**
1109
+ * Bump the `db.r2.put.429_total` counter when `err` looks like an
1110
+ * R2 prefix-partition rate-limit. Best-effort: detected via
1111
+ * `BaerlyError{code:"NetworkError"}` with a `429` token in the
1112
+ * message. Called from every PUT call site's catch arm; mutually
1113
+ * exclusive in practice with `isPreconditionFailed` (412 ≠ 429).
1114
+ */
1115
+ #observe429(err, collection) {
1116
+ if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
1117
+ }
1118
+ /**
1119
+ * Emit the per-logical-write `class_a_ops_per_logical_write`
1120
+ * histogram for `commit`. `classAOps` is the per-attempt base plus
1121
+ * a charge for prior failed attempts (the retry-budget cost model),
1122
+ * computed by the caller.
1123
+ */
1124
+ #emitWriteMetrics(collection, classAOps) {
1125
+ ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
1126
+ }
1127
+ /**
1128
+ * Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
1129
+ * at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
1130
+ * from re-racing in lockstep. Worst-case total wait across the
1131
+ * default 8 attempts is roughly 2.5 s — well under a typical
1132
+ * Worker request budget.
1133
+ */
1134
+ async #backoff(attempt) {
1135
+ const sleepMs = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS) * this.#random();
1136
+ if (sleepMs <= 0) return;
1137
+ await new Promise((r) => setTimeout(r, sleepMs));
1217
1138
  }
1218
- return {
1219
- kind: "index-walk",
1220
- indexName: best.def.name,
1221
- equalityKeys: best.equalityKeys,
1222
- ...best.tail !== void 0 && best.tail.kind === "range" ? { rangeOn: {
1223
- field: best.tail.field,
1224
- ...best.tail.info.lo !== void 0 ? { lo: best.tail.info.lo } : {},
1225
- ...best.tail.info.hi !== void 0 ? { hi: best.tail.info.hi } : {},
1226
- loInclusive: best.tail.info.loInclusive,
1227
- hiInclusive: best.tail.info.hiInclusive
1228
- } } : {},
1229
- ...best.tail !== void 0 && best.tail.kind === "in" ? { inOn: {
1230
- field: best.tail.field,
1231
- values: best.tail.values
1232
- } } : {}
1233
- };
1234
1139
  };
1235
- //#endregion
1236
- //#region packages/server/src/schema.ts
1237
1140
  /**
1238
- * Schema-validator runtime helper for `Db.insert` / `Query.update` /
1239
- * `Collection.replace` boundary checks.
1240
- *
1241
- * The `SchemaValidator` / `SchemaIssue` TYPES live in
1242
- * `@baerly/protocol` (cross-platform). This module owns the runtime
1243
- * helper `validateOrThrow` that runs a validator and raises a
1244
- * `BaerlyError{code:"SchemaError"}` on failure.
1245
- *
1246
- * @example
1247
- * ```ts
1248
- * import { z } from "zod";
1249
- * import { defineConfig } from "@gusto/baerly-storage/config";
1250
- *
1251
- * const Ticket = z.object({
1252
- * _id: z.string(),
1253
- * status: z.enum(["open", "closed"]),
1254
- * title: z.string().min(1),
1255
- * });
1256
- *
1257
- * export default defineConfig({
1258
- * collections: {
1259
- * tickets: { schema: Ticket },
1260
- * },
1261
- * });
1262
- * ```
1141
+ * `true` when the underlying storage surfaced a `PreconditionFailed`
1142
+ * 412 (or its non-S3 equivalents). Every in-tree {@link Storage} impl
1143
+ * surfaces a lost CAS as `BaerlyError{code:"Conflict"}`.
1263
1144
  */
1145
+ const isPreconditionFailed = (err) => err instanceof BaerlyError && err.code === "Conflict";
1264
1146
  /**
1265
- * Run a validator and throw `BaerlyError{code:"SchemaError"}` on failure.
1266
- * On success returns the validator's output (which for transforming
1267
- * validators may differ from the input).
1268
- *
1269
- * Field paths are normalised to `(string | number)[]` so the wire shape
1270
- * is JSON-clean. Symbol keys (rare; StandardSchemaV1 permits them) are
1271
- * coerced to `String(sym)` — we never emit `symbol` on the wire.
1272
- *
1273
- * The thrown error's `message` carries a one-line summary
1274
- * (`"<collection>.<verb>: <issuesCount> field(s) failed validation: <first>"`)
1275
- * for stderr-readable logs; the structured `issues` are on `.issues`.
1147
+ * `true` when a log-create PUT failed transiently (a `NetworkError`) —
1148
+ * the write may or may not have landed (a dropped ack). Safe to retry
1149
+ * the SAME seq: own-session adoption closes the double-commit window if
1150
+ * it did land. NOT a 412 (that's handled by adoption directly).
1276
1151
  */
1277
- const validateOrThrow = async (schema, candidate, context) => {
1278
- const result = await schema["~standard"].validate(candidate);
1279
- if (result.issues === void 0) return result.value;
1280
- const issues = result.issues.map((i) => ({
1281
- path: (i.path ?? []).map((p) => {
1282
- const raw = typeof p === "object" && p !== null && "key" in p ? p.key : p;
1283
- return typeof raw === "number" ? raw : String(raw);
1284
- }),
1285
- message: i.message
1286
- }));
1287
- const first = issues[0];
1288
- const summary = first === void 0 ? "schema validation failed (no issues reported)" : `${first.path.length === 0 ? "<root>" : first.path.join(".")}: ${first.message}`;
1289
- throw new BaerlyError("SchemaError", `${context.collection}.${context.verb}: ${issues.length} field${issues.length === 1 ? "" : "s"} failed validation: ${summary}`, void 0, issues);
1152
+ const isTransientWrite = (err) => err instanceof BaerlyError && err.code === "NetworkError";
1153
+ /**
1154
+ * `true` when the underlying storage surfaced an R2 prefix-partition
1155
+ * rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
1156
+ * onto `BaerlyError.cause` as `{ status }`; we discriminate on that
1157
+ * structured field rather than regex-matching the message.
1158
+ */
1159
+ const is429 = (err) => {
1160
+ if (!(err instanceof BaerlyError) || err.code !== "NetworkError") return false;
1161
+ return err.cause?.status === 429;
1290
1162
  };
1291
1163
  //#endregion
1292
1164
  //#region packages/server/src/query.ts
@@ -1294,8 +1166,8 @@ const validateOrThrow = async (schema, candidate, context) => {
1294
1166
  * Read engine + mutation terminals: `Query<T>` builder, the
1295
1167
  * three read terminals (`first`, `all`, `count`) that fold the log
1296
1168
  * under a fresh `current.json` snapshot, and the four mutation
1297
- * terminals (`insert`, `update`, `replace`, `delete`) that each
1298
- * compile to one or more `Writer.commit()` round-trips.
1169
+ * terminals (`insert`, `update`, `replace`, `delete`). Each mutation
1170
+ * verb compiles to exactly one `Writer.commit()` call.
1299
1171
  *
1300
1172
  * Every modifier (`.where` / `.order` / `.limit`) returns a NEW
1301
1173
  * `Query<T>` carrying merged frozen state — the input state is never
@@ -1306,28 +1178,44 @@ const validateOrThrow = async (schema, candidate, context) => {
1306
1178
  * AND on the normalised wire form).
1307
1179
  * `.order()` and `.limit()` are last-call-wins (state replace).
1308
1180
  *
1309
- * Each terminal reads `current.json` FRESH and walks `[0, next_seq)`
1310
- * directly — no cache, no `list()` round-trip. Per the multi-
1311
- * instance rules, every read sees a fresh CAS snapshot.
1181
+ * Each terminal reads `current.json` FRESH, loads the snapshot it names,
1182
+ * and walks `[log_seq_start, tail_hint)` directly — no cache, no
1183
+ * `list()` round-trip for the log. Per the multi-instance rules, every
1184
+ * read sees a fresh CAS snapshot.
1312
1185
  *
1313
1186
  * Mutation terminals are SINGLE-ATTEMPT per call site. CAS contention
1314
1187
  * retries (up to 8 attempts) live inside `Writer.commit()`; the
1315
1188
  * verbs do NOT add their own retry loop. On retry-budget exhaustion
1316
1189
  * `commit()` throws `BaerlyError{code:"Conflict"}` and the verb
1317
- * surfaces it unchanged — the caller's option is to wrap in
1318
- * `db.transaction(...)`.
1190
+ * surfaces it unchanged — the caller decides whether to re-run.
1319
1191
  *
1320
1192
  * @see ../../../docs/spec/sync-protocol.md
1321
1193
  */
1194
+ const DUPLICATE_ID_RESOLUTION = "Use different `_id` or omit it.";
1322
1195
  /**
1323
- * Serialise a {@link CurrentJson} head into the wire cursor format
1324
- * `"<snapshot>@<next_seq>"`. `null` snapshots stringify as
1325
- * {@link MANIFEST_POINTER_EMPTY_SNAPSHOT} so the cursor is never the
1326
- * empty string.
1196
+ * Serialise a {@link CurrentJson} head into an opaque wire cursor.
1197
+ * `tail` is the DISCOVERED tail (defaults to `json.tail_hint` when no
1198
+ * probe has run). Physical snapshot keys feed the digest but never
1199
+ * cross the HTTP boundary.
1327
1200
  *
1328
1201
  * @internal — exported for `query.test.ts`.
1329
1202
  */
1330
- const serializeManifestPointer = (json) => `${json.snapshot ?? "none"}@${json.next_seq}`;
1203
+ const manifestPointerDigest = (seed) => {
1204
+ let hash = 14695981039346656037n;
1205
+ for (let i = 0; i < seed.length; i++) {
1206
+ hash ^= BigInt(seed.charCodeAt(i));
1207
+ hash = hash * 1099511628211n & 18446744073709551615n;
1208
+ }
1209
+ return hash.toString(36).padStart(13, "0");
1210
+ };
1211
+ const serializeManifestPointer = (json, tail = json.tail_hint) => `m1:${manifestPointerDigest([
1212
+ json.snapshot ?? "none",
1213
+ json.log_seq_start,
1214
+ json.tail_hint,
1215
+ json.snapshot_bytes,
1216
+ json.snapshot_rows,
1217
+ tail
1218
+ ].join("|"))}`;
1331
1219
  /**
1332
1220
  * Returns the id iff `wire` carries exactly one clause and that
1333
1221
  * clause is `{op:"eq", field:"_id", value:<string>}` — the shape
@@ -1493,6 +1381,7 @@ const writerFor = (ctx) => new Writer({
1493
1381
  const runInsert = async (ctx, doc) => {
1494
1382
  const supplied = doc["_id"];
1495
1383
  const _id = typeof supplied === "string" && supplied.length > 0 ? supplied : uuidv7();
1384
+ assertDocId(_id);
1496
1385
  const body = {
1497
1386
  ...doc,
1498
1387
  _id
@@ -1509,16 +1398,7 @@ const runInsert = async (ctx, doc) => {
1509
1398
  }] },
1510
1399
  order: void 0,
1511
1400
  limit: 1
1512
- })).rows.length > 0) throw new BaerlyError("Conflict", `Query.insert: _id ${JSON.stringify(_id)} already exists in collection ${JSON.stringify(ctx.collectionName)}`);
1513
- if (ctx.txCtx !== void 0) {
1514
- assertTxBindMatches(ctx);
1515
- ctx.txCtx.mutations.push({
1516
- op: "I",
1517
- docId: _id,
1518
- body
1519
- });
1520
- return { _id };
1521
- }
1401
+ })).rows.length > 0) throw new BaerlyError("Conflict", `Query.insert: _id ${JSON.stringify(_id)} already exists in collection ${JSON.stringify(ctx.collectionName)}`, void 0, void 0, void 0, DUPLICATE_ID_RESOLUTION, false);
1522
1402
  await writerFor(ctx).commit({
1523
1403
  op: "I",
1524
1404
  collection: ctx.collectionName,
@@ -1535,8 +1415,8 @@ const runInsert = async (ctx, doc) => {
1535
1415
  *
1536
1416
  * Atomicity is per row, not across the N-row batch. The locked
1537
1417
  * contract (`packages/protocol/src/collection-api.ts:178–184`) is explicit on
1538
- * this: all-or-nothing across multiple rows is what
1539
- * `db.transaction(...)` exists to deliver.
1418
+ * this: each affected row commits independently — the document is the
1419
+ * atomic unit; there is no multi-row batch.
1540
1420
  *
1541
1421
  * `replica_identity` defaults to `PATCH_ONLY` for every collection
1542
1422
  * today — emitted `U` entries carry `{ after }` (the full post-image)
@@ -1553,8 +1433,6 @@ const runInsert = async (ctx, doc) => {
1553
1433
  */
1554
1434
  const runUpdate = async (ctx, state, patch) => {
1555
1435
  const { rows } = await runRead(ctx, state);
1556
- const tx = ctx.txCtx;
1557
- if (tx !== void 0) assertTxBindMatches(ctx);
1558
1436
  let modified = 0;
1559
1437
  for (const doc of rows) {
1560
1438
  const merged = merge(doc, patch);
@@ -1563,12 +1441,7 @@ const runUpdate = async (ctx, state, patch) => {
1563
1441
  collection: ctx.collectionName,
1564
1442
  verb: "update"
1565
1443
  });
1566
- if (tx !== void 0) tx.mutations.push({
1567
- op: "U",
1568
- docId: String(doc["_id"]),
1569
- body: merged
1570
- });
1571
- else await writerFor(ctx).commit({
1444
+ await writerFor(ctx).commit({
1572
1445
  op: "U",
1573
1446
  collection: ctx.collectionName,
1574
1447
  docId: String(doc["_id"]),
@@ -1581,8 +1454,7 @@ const runUpdate = async (ctx, state, patch) => {
1581
1454
  /**
1582
1455
  * `Collection.replace` implementation. Existence check via `runRead` over
1583
1456
  * a `byId`-shaped wire so the `singleIdFromPredicate` PK fast path
1584
- * (`Map.get`) fires and any transaction-buffered insert of `id` is
1585
- * visible. Missing row → `NotFound` directly (no Conflict-string
1457
+ * (`Map.get`) fires. Missing row → `NotFound` directly (no Conflict-string
1586
1458
  * indirection through the router). Present row → emit a single
1587
1459
  * `op:"U"` `LogEntry` carrying `doc` as the post-image, with `_id`
1588
1460
  * forced to the requested `id` so doc identity is preserved across
@@ -1595,6 +1467,7 @@ const runUpdate = async (ctx, state, patch) => {
1595
1467
  * exhausted.
1596
1468
  */
1597
1469
  const runReplaceById = async (ctx, id, doc) => {
1470
+ assertDocId(id);
1598
1471
  const { rows } = await runRead(ctx, {
1599
1472
  wire: { clauses: [{
1600
1473
  op: "eq",
@@ -1613,15 +1486,6 @@ const runReplaceById = async (ctx, id, doc) => {
1613
1486
  collection: ctx.collectionName,
1614
1487
  verb: "replace"
1615
1488
  });
1616
- if (ctx.txCtx !== void 0) {
1617
- assertTxBindMatches(ctx);
1618
- ctx.txCtx.mutations.push({
1619
- op: "U",
1620
- docId: id,
1621
- body
1622
- });
1623
- return;
1624
- }
1625
1489
  await writerFor(ctx).commit({
1626
1490
  op: "U",
1627
1491
  collection: ctx.collectionName,
@@ -1638,8 +1502,8 @@ const runReplaceById = async (ctx, id, doc) => {
1638
1502
  * maintain a shadow table — see `packages/protocol/src/log.ts:102–118`.
1639
1503
  *
1640
1504
  * Atomicity is per row, not across the N-row batch — same shape as
1641
- * `Query.update`. `db.transaction(...)` is where all-or-nothing
1642
- * semantics live.
1505
+ * `Query.update`. The document is the atomic unit; there is no
1506
+ * multi-row batch.
1643
1507
  *
1644
1508
  * @throws BaerlyError code="Conflict" — any one row's CAS retry budget
1645
1509
  * exhausted. The partial-progress `deleted` count is NOT returned
@@ -1647,15 +1511,9 @@ const runReplaceById = async (ctx, id, doc) => {
1647
1511
  */
1648
1512
  const runDelete = async (ctx, state) => {
1649
1513
  const { rows } = await runRead(ctx, state);
1650
- const tx = ctx.txCtx;
1651
- if (tx !== void 0) assertTxBindMatches(ctx);
1652
1514
  let deleted = 0;
1653
1515
  for (const doc of rows) {
1654
- if (tx !== void 0) tx.mutations.push({
1655
- op: "D",
1656
- docId: String(doc["_id"])
1657
- });
1658
- else await writerFor(ctx).commit({
1516
+ await writerFor(ctx).commit({
1659
1517
  op: "D",
1660
1518
  collection: ctx.collectionName,
1661
1519
  docId: String(doc["_id"])
@@ -1665,55 +1523,46 @@ const runDelete = async (ctx, state) => {
1665
1523
  return { deleted };
1666
1524
  };
1667
1525
  /**
1668
- * Runtime guard for the txCtx-Collection-name binding. The type system
1669
- * already prevents the legitimate path (the body callback gets one
1670
- * `Collection<T>`, no `Db`), so this only catches a bug where a stale
1671
- * `Query<T>` outlives its `Collection<T>` and is somehow re-attached to a
1672
- * transaction over a different collection.
1673
- *
1674
- * @throws BaerlyError code="Internal" — txCtx ↔ Collection name mismatch.
1675
- */
1676
- const assertTxBindMatches = (ctx) => {
1677
- if (ctx.txCtx === void 0) return;
1678
- if (ctx.txCtx.collection !== ctx.collectionName) throw new BaerlyError("Internal", `Transaction context bound to ${JSON.stringify(ctx.txCtx.collection)} but mutation issued on collection ${JSON.stringify(ctx.collectionName)}`);
1679
- };
1680
- /**
1681
- * Load `current.json` fresh, walk `[0, next_seq)` in parallel, fold
1526
+ * Load `current.json` fresh, walk `[log_seq_start, tail_hint)` in parallel, fold
1682
1527
  * per-`doc_id`, then apply predicate / order / limit in memory.
1683
1528
  *
1684
1529
  * Error mapping:
1685
1530
  * - `current.json` missing → empty result (collection not provisioned).
1686
1531
  * - `current.json` malformed → `InvalidResponse` (from `readCurrentJson`).
1687
- * - log entry missing in `[0, next_seq)` → `Internal`.
1532
+ * - log entry missing in `[log_seq_start, tail_hint)` → `Internal`.
1688
1533
  * - log entry malformed → `InvalidResponse`.
1689
1534
  */
1690
1535
  const runRead = async (ctx, state) => {
1691
1536
  const currentJsonKey = `${ctx.collectionPrefix}/current.json`;
1692
1537
  const head = await readCurrentJson(ctx.storage, currentJsonKey);
1693
- const manifestPointer = head === null ? `${MANIFEST_POINTER_EMPTY_SNAPSHOT}@0` : serializeManifestPointer(head.json);
1694
1538
  const fresh = true;
1695
1539
  if (head === null) return {
1696
1540
  rows: [],
1697
- manifestPointer,
1541
+ manifestPointer: "m1:0000000000000",
1698
1542
  fresh
1699
1543
  };
1700
1544
  const plan = planQuery(state.wire, ctx.indexes);
1701
1545
  if (plan.kind === "index-walk") {
1702
- let rows = await runIndexWalkPlan(ctx, head.json, state, plan);
1546
+ const walk = await runIndexWalkPlan(ctx, head.json, state, plan);
1547
+ let rows = walk.rows;
1703
1548
  if (state.order !== void 0) rows = sortByOrderSpec(rows, state.order);
1704
1549
  if (state.limit !== void 0 && state.limit < rows.length) rows = rows.slice(0, state.limit);
1705
1550
  return {
1706
1551
  rows,
1707
- manifestPointer,
1552
+ manifestPointer: serializeManifestPointer(head.json, walk.tail),
1708
1553
  fresh
1709
1554
  };
1710
1555
  }
1711
- const nextSeq = head.json.next_seq;
1556
+ const hint = head.json.tail_hint;
1712
1557
  const logSeqStart = logSeqStartOf(head.json);
1713
1558
  const baseDocs = head.json.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.json.snapshot, ctx.collectionName);
1714
- const entries = await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, nextSeq);
1559
+ const probeFrom = Math.max(logSeqStart, hint);
1560
+ const entries = await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, hint);
1561
+ const probe = await probeTailFrom(ctx.storage, ctx.collectionPrefix, probeFrom);
1562
+ const tail = probe.tail;
1715
1563
  const docs = new Map(baseDocs);
1716
1564
  foldLogEntriesOnto(docs, entries, { collection: ctx.collectionName });
1565
+ foldLogEntriesOnto(docs, probe.entries, { collection: ctx.collectionName });
1717
1566
  const fastId = singleIdFromPredicate(state.wire);
1718
1567
  let rows;
1719
1568
  if (fastId !== void 0) {
@@ -1730,7 +1579,7 @@ const runRead = async (ctx, state) => {
1730
1579
  if (state.limit !== void 0 && state.limit < rows.length) rows = rows.slice(0, state.limit);
1731
1580
  return {
1732
1581
  rows,
1733
- manifestPointer,
1582
+ manifestPointer: serializeManifestPointer(head.json, tail),
1734
1583
  fresh
1735
1584
  };
1736
1585
  };
@@ -1859,8 +1708,15 @@ const runIndexWalkPlan = async (ctx, head, state, plan) => {
1859
1708
  if (docId.length === 0) continue;
1860
1709
  docIdSet.add(docId);
1861
1710
  }
1711
+ const logSeqStart = logSeqStartOf(head);
1712
+ const hint = head.tail_hint;
1713
+ const probe = await probeTailFrom(ctx.storage, ctx.collectionPrefix, Math.max(logSeqStart, hint));
1714
+ const tail = probe.tail;
1862
1715
  const docIds = Array.from(docIdSet);
1863
- if (docIds.length === 0) return [];
1716
+ if (docIds.length === 0) return {
1717
+ rows: [],
1718
+ tail
1719
+ };
1864
1720
  const matched = new Set(docIds);
1865
1721
  const baseDocs = head.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.snapshot, ctx.collectionName);
1866
1722
  const docs = /* @__PURE__ */ new Map();
@@ -1868,16 +1724,21 @@ const runIndexWalkPlan = async (ctx, head, state, plan) => {
1868
1724
  const seeded = baseDocs.get(id);
1869
1725
  if (seeded !== void 0) docs.set(id, seeded);
1870
1726
  }
1871
- const logSeqStart = logSeqStartOf(head);
1872
- const nextSeq = head.next_seq;
1873
- foldLogEntriesOnto(docs, await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, nextSeq), {
1727
+ foldLogEntriesOnto(docs, await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, hint), {
1728
+ collection: ctx.collectionName,
1729
+ docIdFilter: matched
1730
+ });
1731
+ foldLogEntriesOnto(docs, probe.entries, {
1874
1732
  collection: ctx.collectionName,
1875
1733
  docIdFilter: matched
1876
1734
  });
1877
1735
  const rows = [];
1878
1736
  const wire = state.wire;
1879
1737
  for (const doc of docs.values()) if (wire === void 0 || matchesWire(wire, doc)) rows.push(doc);
1880
- return rows;
1738
+ return {
1739
+ rows,
1740
+ tail
1741
+ };
1881
1742
  };
1882
1743
  /**
1883
1744
  * Stable multi-key sort built from an `OrderSpec`. Keys are taken in
@@ -1907,6 +1768,6 @@ const sortByOrderSpec = (rows, spec) => {
1907
1768
  });
1908
1769
  };
1909
1770
  //#endregion
1910
- export { runReplaceById as a, lsnParts as c, runInsert as i, delay as l, runAllWithMeta as n, validateOrThrow as o, runByIdWithMeta as r, Writer as s, makeQuery as t };
1771
+ export { runReplaceById as a, runInsert as i, runAllWithMeta as n, validateOrThrow as o, runByIdWithMeta as r, assertPathSegment as s, makeQuery as t };
1911
1772
 
1912
- //# sourceMappingURL=query-BmiQy328.js.map
1773
+ //# sourceMappingURL=query-rAtXNQQB.js.map