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