@gusto/baerly-storage 0.2.0 → 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 (122) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +29 -0
  3. package/README.md +93 -52
  4. package/dist/API.md +151 -109
  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 +3 -3
  17. package/dist/client-react.js.map +1 -1
  18. package/dist/client.d.ts +3 -3
  19. package/dist/client.js.map +1 -1
  20. package/dist/{cloudflare-CINJPKCW.js → cloudflare-Cn2ibODt.js} +178 -2
  21. package/dist/cloudflare-Cn2ibODt.js.map +1 -0
  22. package/dist/cloudflare.d.ts +4 -4
  23. package/dist/cloudflare.js +10 -11
  24. package/dist/cloudflare.js.map +1 -1
  25. package/dist/{subcommand-DZcHcsYp.js → config-CGyBopy3.js} +643 -439
  26. package/dist/config-CGyBopy3.js.map +1 -0
  27. package/dist/context-DRZ3tZ5l.js.map +1 -1
  28. package/dist/{cost-CQt1YRkA.js → cost-BZ_MDBmn.js} +6 -4
  29. package/dist/cost-BZ_MDBmn.js.map +1 -0
  30. package/dist/{current-json-C-EyJqs0.js → current-json-DsN7FNY1.js} +47 -13
  31. package/dist/current-json-DsN7FNY1.js.map +1 -0
  32. package/dist/{db-BM3y2JQw.d.ts → db-CCT6tDfY.d.ts} +26 -108
  33. package/dist/{deploy-CrAbfgCq.js → deploy-BKKyGlSJ.js} +11 -4
  34. package/dist/deploy-BKKyGlSJ.js.map +1 -0
  35. package/dist/dev-vite.d.ts +5 -5
  36. package/dist/dev-vite.js +5 -5
  37. package/dist/dev-vite.js.map +1 -1
  38. package/dist/dev.d.ts +1 -1
  39. package/dist/dev.js +1 -1
  40. package/dist/{doctor-Db-hzPmE.js → doctor-BVU4GNXN.js} +13 -132
  41. package/dist/doctor-BVU4GNXN.js.map +1 -0
  42. package/dist/{dump-BYA55NLP.js → dump-DPEAKub6.js} +5 -3
  43. package/dist/dump-DPEAKub6.js.map +1 -0
  44. package/dist/errors-DOdL95kK.js.map +1 -1
  45. package/dist/{export-Bhbz90-z.js → export-BcuCLFFe.js} +6 -4
  46. package/dist/{export-Bhbz90-z.js.map → export-BcuCLFFe.js.map} +1 -1
  47. package/dist/{fsck-CPPZWt9p.js → fsck-RXgLOaJG.js} +23 -11
  48. package/dist/fsck-RXgLOaJG.js.map +1 -0
  49. package/dist/{http-Cw8p6y5b.js → http-Bd4byR4n.js} +45 -61
  50. package/dist/http-Bd4byR4n.js.map +1 -0
  51. package/dist/http.d.ts +15 -15
  52. package/dist/http.js +1 -1
  53. package/dist/{index-cUY-36AN.d.ts → index-BDceQQi-.d.ts} +20 -4
  54. package/dist/{index-C3JAH1Yo.d.ts → index-Cmsxx-ZN.d.ts} +9 -9
  55. package/dist/{index-DSvwEUeF.d.ts → index-DW7GT6M2.d.ts} +50 -42
  56. package/dist/{index-DwDTWPSU.d.ts → index-DnBGSeuU.d.ts} +10 -7
  57. package/dist/index.d.ts +6 -6
  58. package/dist/index.js +4 -4
  59. package/dist/{indexes-DAu2AkTW.d.ts → indexes-Cx7uMXm0.d.ts} +2 -2
  60. package/dist/{inspect-Bdbzvi-_.js → inspect-DhI49PSi.js} +16 -8
  61. package/dist/inspect-DhI49PSi.js.map +1 -0
  62. package/dist/{snapshot-SS8USDUF.js → log-tail-DXeDkWEp.js} +154 -83
  63. package/dist/log-tail-DXeDkWEp.js.map +1 -0
  64. package/dist/{maintenance-BRrThz8V.d.ts → maintenance-BkhUr72A.d.ts} +91 -26
  65. package/dist/{maintenance-ClzBC1Vv.js → maintenance-CWBQpZ2y.js} +368 -161
  66. package/dist/maintenance-CWBQpZ2y.js.map +1 -0
  67. package/dist/{maintenance-BvOv6BMM.js → maintenance-C_KSkVjd.js} +204 -82
  68. package/dist/maintenance-C_KSkVjd.js.map +1 -0
  69. package/dist/maintenance.d.ts +3 -2
  70. package/dist/maintenance.js +3 -2
  71. package/dist/node.d.ts +13 -8
  72. package/dist/node.js +1 -1
  73. package/dist/normalize-XWY25_sG.js.map +1 -1
  74. package/dist/{observability-CpOiEN0k.js → observability-BYd-RzEx.js} +63 -55
  75. package/dist/observability-BYd-RzEx.js.map +1 -0
  76. package/dist/observability.d.ts +3 -3
  77. package/dist/observability.js +1 -1
  78. package/dist/{plan-DOTl21vq.js → plan-DIu_B6fy.js} +7 -4
  79. package/dist/plan-DIu_B6fy.js.map +1 -0
  80. package/dist/{query-BmiQy328.js → query-sQNO5vU_.js} +1071 -1099
  81. package/dist/query-sQNO5vU_.js.map +1 -0
  82. package/dist/{rebuild-index-DC_nR6wP.js → rebuild-index-DP4CqSSs.js} +5 -4
  83. package/dist/rebuild-index-DP4CqSSs.js.map +1 -0
  84. package/dist/{restore-C6IcmLeA.js → restore-DpQYef6r.js} +362 -328
  85. package/dist/restore-DpQYef6r.js.map +1 -0
  86. package/dist/shared-secret-BJdSwpgw.js.map +1 -1
  87. package/dist/{src-QQ7jDeL2.js → src-CWpkSbvJ.js} +40 -20
  88. package/dist/src-CWpkSbvJ.js.map +1 -0
  89. package/dist/{src-DU1sCMlr.js → src-D24wDpzR.js} +269 -258
  90. package/dist/src-D24wDpzR.js.map +1 -0
  91. package/dist/{src-zhEAmmF7.js → src-Db4-qVtM.js} +36 -96
  92. package/dist/src-Db4-qVtM.js.map +1 -0
  93. package/dist/subcommand-CP9NY2J4.js +159 -0
  94. package/dist/subcommand-CP9NY2J4.js.map +1 -0
  95. package/dist/{usage-CLjirdD-.js → usage-CTfDq9HR.js} +3 -3
  96. package/dist/{usage-CLjirdD-.js.map → usage-CTfDq9HR.js.map} +1 -1
  97. package/dist/{validate-DCq_0DIn.js → validate-DtljsCh1.js} +51 -51
  98. package/dist/{validate-DCq_0DIn.js.map → validate-DtljsCh1.js.map} +1 -1
  99. package/package.json +40 -29
  100. package/dist/cloudflare-CINJPKCW.js.map +0 -1
  101. package/dist/config-DVfDGyw1.js +0 -278
  102. package/dist/config-DVfDGyw1.js.map +0 -1
  103. package/dist/cost-CQt1YRkA.js.map +0 -1
  104. package/dist/current-json-C-EyJqs0.js.map +0 -1
  105. package/dist/deploy-CrAbfgCq.js.map +0 -1
  106. package/dist/doctor-Db-hzPmE.js.map +0 -1
  107. package/dist/dump-BYA55NLP.js.map +0 -1
  108. package/dist/fsck-CPPZWt9p.js.map +0 -1
  109. package/dist/http-Cw8p6y5b.js.map +0 -1
  110. package/dist/inspect-Bdbzvi-_.js.map +0 -1
  111. package/dist/maintenance-BvOv6BMM.js.map +0 -1
  112. package/dist/maintenance-ClzBC1Vv.js.map +0 -1
  113. package/dist/observability-CpOiEN0k.js.map +0 -1
  114. package/dist/plan-DOTl21vq.js.map +0 -1
  115. package/dist/query-BmiQy328.js.map +0 -1
  116. package/dist/rebuild-index-DC_nR6wP.js.map +0 -1
  117. package/dist/restore-C6IcmLeA.js.map +0 -1
  118. package/dist/snapshot-SS8USDUF.js.map +0 -1
  119. package/dist/src-DU1sCMlr.js.map +0 -1
  120. package/dist/src-QQ7jDeL2.js.map +0 -1
  121. package/dist/src-zhEAmmF7.js.map +0 -1
  122. package/dist/subcommand-DZcHcsYp.js.map +0 -1
@@ -1,9 +1,37 @@
1
1
  import { n as encodeJsonBytes, t as decodeJsonBytes } from "./bytes-BXdamO3L.js";
2
- import { a as readLogEntry, d as logSeqStartOf, f as readCurrentJson, o as walkLogRange, u as createCurrentJson } from "./snapshot-SS8USDUF.js";
3
- import { a as getCurrentContext, c as noopMetricsRecorder, l as versionFromContent, n as runBoundedMaintenance, o as allIndexKeysFor, r as shouldFireMaintenance, s as validateIndexDefinition, t as dispatchInlineAwaited } from "./maintenance-BvOv6BMM.js";
4
- import { a as uuid, i as countKey, n as parseBucketUri, r as timestamp, t as defineBaerlySubcommand } from "./subcommand-DZcHcsYp.js";
2
+ import { a as countKey, d as LOG_FORWARD_PROBE_CAP, h as MAX_KEY_BYTES, i as timestamp, o as uuid, p as MAINTENANCE_PROFILE_CF_FREE, r as parseBucketUri } from "./config-CGyBopy3.js";
3
+ import { a as walkLogRange, d as logObjectKey, h as readCurrentJson, i as readLogEntry, m as logSeqStartOf, p as createCurrentJson, t as findLogTail } from "./log-tail-DXeDkWEp.js";
4
+ import { a as getCurrentContext, c as noopMetricsRecorder, l as versionFromContent, n as runBoundedMaintenance, o as allIndexKeysFor, r as shouldFireMaintenance, s as validateIndexDefinition, t as dispatchInlineAwaited } from "./maintenance-C_KSkVjd.js";
5
5
  import { o as BaerlyError, r as emitSuccess } from "./baerly.js";
6
+ import { n as defineBaerlySubcommand, r as assertPathSegment, t as assertCollectionArg } from "./subcommand-CP9NY2J4.js";
6
7
  import { createInterface } from "node:readline";
8
+ //#region ../server/src/doc-id.ts
9
+ /**
10
+ * Guard a caller-supplied `_id` before it becomes a written key segment
11
+ * (index keys, log `doc_id`) or filesystem path (`LocalFsStorage`). The
12
+ * `_id` analogue of `assertKeySegment` (`db.ts`). Routes through the
13
+ * single shared {@link assertPathSegment} rule (empty / `"/"` /
14
+ * `"."`|`".."` / C0-C1 control chars / leading `"_"` (ADR-007) / overlong,
15
+ * all as `BaerlyError{code:"InvalidConfig"}`).
16
+ */
17
+ const assertDocId = (id) => {
18
+ assertPathSegment(id, "_id");
19
+ };
20
+ //#endregion
21
+ //#region ../server/src/key-limit.ts
22
+ const utf8 = new TextEncoder();
23
+ /**
24
+ * Reject an assembled object key over the S3/R2 full-key ceiling
25
+ * ({@link MAX_KEY_BYTES}) as `InvalidConfig`. Per-segment caps don't
26
+ * bound the sum, and index values skip `assertPathSegment` entirely, so
27
+ * this post-encoding check at the writer's PUT sites is their only
28
+ * overflow guard. @see docs/spec/storage-compatibility.md
29
+ */
30
+ const assertKeyWithinLimit = (key) => {
31
+ const bytes = utf8.encode(key).length;
32
+ if (bytes > 1024) throw new BaerlyError("InvalidConfig", `object key exceeds ${MAX_KEY_BYTES} bytes (got ${bytes}): ${JSON.stringify(key.slice(0, 80))}…`);
33
+ };
34
+ //#endregion
7
35
  //#region ../server/src/log-conflict-adoption.ts
8
36
  /**
9
37
  * Decide whether the entry already at `/log/<seq>.json` is the
@@ -11,6 +39,15 @@ import { createInterface } from "node:readline";
11
39
  * function; no I/O. The caller performs the GET (when the log PUT
12
40
  * surfaces 412) and passes the read-back body in `ctx.existing`.
13
41
  *
42
+ * ## Correctness precondition
43
+ *
44
+ * A fresh `session` id is minted per `commit()` call, seq-stable
45
+ * across that call's retries. Adoption compares the writer-minted
46
+ * intent/body fields as well as session and seq: a dropped-ack retry
47
+ * reuses the same attempted entry and adopts, while a same-session /
48
+ * same-seq occupant carrying a different logical mutation is treated as
49
+ * a conflict and skipped by the caller's forward-probe loop.
50
+ *
14
51
  * @see {@link AdoptionDecision} for the return shape.
15
52
  * @see The soundness invariant in this module's header docstring.
16
53
  */
@@ -27,6 +64,10 @@ const tryAdoptOwnSessionLogEntry = (ctx) => {
27
64
  adopt: false,
28
65
  reason: "wrong-seq"
29
66
  };
67
+ if (JSON.stringify(ctx.existing) !== JSON.stringify(ctx.self)) return {
68
+ adopt: false,
69
+ reason: "intent-mismatch"
70
+ };
30
71
  return {
31
72
  adopt: true,
32
73
  entry: ctx.existing
@@ -35,29 +76,37 @@ const tryAdoptOwnSessionLogEntry = (ctx) => {
35
76
  //#endregion
36
77
  //#region ../server/src/writer.ts
37
78
  /**
38
- * `Writer` — stateless multi-instance write engine.
79
+ * `Writer` — stateless multi-instance write engine (single-write commit).
39
80
  *
40
- * Each {@link Writer.commit} call reads `current.json` FRESH from
41
- * the bucket, mints the next {@link LogEntry}, PUTs the content body
42
- * and the log entry, and CAS-advances `current.json` with `If-Match`.
43
- * Up to {@link S3_REQUEST_MAX_RETRIES} attempts on contention before
44
- * surfacing `BaerlyError{code:"Conflict"}`. The optional integrity
45
- * walk over the live log tail is gated by
46
- * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off
47
- * — see the option's docstring).
81
+ * Each {@link Writer.commit} reads `current.json` FRESH (for
82
+ * `log_seq_start` / `tail_hint` as a probe FLOOR — a lower bound, NOT a
83
+ * CAS precondition), PUTs the content body, then **creates `log/<seq>`
84
+ * via `If-None-Match: "*"`. That create IS the commit / linearization
85
+ * point.** The writer writes NOTHING to `current.json` on the commit
86
+ * path; `tail_hint` advances outside ordinary commits via compaction
87
+ * folds, write-tick refreshes, and explicit operator/import paths. The
88
+ * commit model and its invariants are recorded in ADR-008
89
+ * (`docs/adr/008-single-write-commit.md`). The
90
+ * optional integrity walk is gated by
91
+ * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off).
48
92
  *
49
- * The instance carries no per-write cache: every commit re-reads
50
- * `current.json`, so N stateless server instances writing the same
51
- * tenant prefix contend at exactly one place — the conditional PUT
52
- * on `current.json` — and one loses cleanly with a 412.
93
+ * No per-write cache: every commit re-reads + re-probes, so N stateless
94
+ * instances contend at one place — the `If-None-Match` create of
95
+ * `log/<seq>`. The loser gets a 412 and re-probes forward to the next
96
+ * empty slot. A 412 from the writer's OWN session at the same seq is its
97
+ * own lost-ack / crashed-but-durable commit → adopted (not retried), so
98
+ * the write lands at EXACTLY `seq`, never duplicated.
53
99
  *
54
- * **Manifest-first ordering is REVERSED relative to the legacy
55
- * `src/syncer.ts` write loop.** Old loop: PUT manifest → PUT content
56
- * → CAS. New loop: PUT content → PUT log entry → CAS-advance
57
- * `current.json`. A crashed mid-loop writer leaves an unreferenced
58
- * content body (no log entry points at it), not an orphan log entry
59
- * with missing content. The compactor sweeps the orphan content
60
- * later.
100
+ * **Crash safety.** Order is content + additive index `newKeys` →
101
+ * `log/<seq>` create → stale index-key DELETEs. A crash before the
102
+ * create leaves an unreferenced content body + orphan additive index
103
+ * keys (no log entry references them), not an orphan log entry with
104
+ * missing content — the compactor sweeps the content, and a stray
105
+ * additive key only ever yields a false-POSITIVE candidate that
106
+ * `matchesWire` (read path) drops. Emitting `newKeys` before the commit
107
+ * means a committed row is ALWAYS index-findable; the stale-key DELETE
108
+ * stays after the commit so a crash can never de-index a committed
109
+ * doc. See `index-emit-order.test.ts` and ADR-008 Q4.
61
110
  *
62
111
  * **`LogEntry` shape.** Emitted entries follow the contract in
63
112
  * `packages/protocol/src/log.ts` (see {@link LogEntry}) and
@@ -127,33 +176,33 @@ var Writer = class {
127
176
  this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
128
177
  }
129
178
  /**
130
- * Atomically commit one mutation. Reads `current.json` fresh, mints
131
- * the next log entry at `seq = current.next_seq`, PUTs the content
132
- * body and the log entry, then CAS-advances `current.json` with
133
- * `If-Match`. Retries on conflict up to `maxRetries`.
179
+ * Atomically commit one mutation. Reads `current.json` fresh (as a
180
+ * probe FLOOR, not a CAS precondition), PUTs the content body and any
181
+ * additive index `newKeys`, then creates `log/<seq>` via
182
+ * `If-None-Match: "*"` — that create IS the commit (single-write
183
+ * commit; no `current.json` CAS follows it). Stale index keys are
184
+ * DELETE'd after the commit.
134
185
  *
135
- * The hot-path cost under no contention is 1 GET + 3 PUTs (4 ops);
136
- * an in-flight peer write costs one extra GET + the backoff sleep
137
- * per retry.
186
+ * The hot-path cost under no contention on an unindexed collection is
187
+ * 1 GET + 2 PUTs (content + the committing `log/<seq>` create); each
188
+ * declared index that projects a key on this write adds one PUT
189
+ * (new key, before the commit) and, on U/D, up to one DELETE (stale
190
+ * key, after the commit). An in-flight peer write costs one extra GET
191
+ * + the backoff sleep per retry.
138
192
  *
139
193
  * Idempotency: PUT content uses `If-None-Match: "*"`, so a retry of
140
194
  * the same logical write produces the same content key and the
141
- * second PUT no-ops. PUT log entry also uses `If-None-Match: "*"`,
142
- * so two writers racing the same `next_seq` cause exactly one PUT
143
- * to land — the loser falls into the CAS retry path.
195
+ * second PUT no-ops. The `log/<seq>` create also uses
196
+ * `If-None-Match: "*"`, so two writers racing the same tail cause
197
+ * exactly one create to win; the loser reads back the occupant,
198
+ * adopts its own lost-ack write or re-probes forward to the next
199
+ * empty slot.
144
200
  *
145
- * @throws BaerlyError code="Conflict" when the retry budget is
146
- * exhausted (genuine high-contention case), or when the underlying
147
- * `current.json` CAS PUT lost.
148
- * @throws BaerlyError code="Conflict" — the writer fence
149
- * (`current.json.writer_fence.epoch`) was bumped by a concurrent
150
- * `claimWriter` call between this commit's read of
151
- * `current.json` and its CAS-advance. The stale writer aborts
152
- * to honour the new authority — the kernel does NOT retry under
153
- * the old epoch. See {@link claimWriter} for the rotation
154
- * recipe.
201
+ * @throws BaerlyError code="Conflict" when a retryable conflict
202
+ * escapes the single-attempt helper and exhausts the retry budget
203
+ * (presently unreachable on the log-create 412 path).
155
204
  * @throws BaerlyError code="Internal" when a log entry expected in
156
- * `[0, next_seq)` is missing — a protocol-invariant violation
205
+ * `[0, tail_hint)` is missing — a protocol-invariant violation
157
206
  * (compactor bug or stale `current.json`).
158
207
  * @throws BaerlyError code="InvalidResponse" when a log-entry body
159
208
  * isn't valid JSON.
@@ -167,18 +216,18 @@ var Writer = class {
167
216
  * and re-reads to pick up the winner's manifest.
168
217
  */
169
218
  async commit(input) {
219
+ assertDocId(input.docId);
170
220
  const session = uuid().slice(0, 6);
171
221
  const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
172
222
  for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {
173
223
  let success;
174
224
  try {
175
- success = await this.#singleAttemptCommit([input], session, logPrefix, "Writer", true);
225
+ success = await this.#singleAttemptCommit([input], session, logPrefix, "Writer");
176
226
  } catch (error) {
177
227
  if (!isPreconditionFailed(error)) throw error;
178
228
  await this.#backoff(attempt);
179
229
  continue;
180
230
  }
181
- await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer");
182
231
  this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));
183
232
  return {
184
233
  entry: success.entries[0],
@@ -189,117 +238,68 @@ var Writer = class {
189
238
  throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`);
190
239
  }
191
240
  /**
192
- * Single-attempt batched commit. Reads `current.json` ONCE, mints
193
- * `inputs.length` log entries with contiguous `seq` numbers
194
- * starting at the current `next_seq`, PUTs each content body and
195
- * each log entry, then CAS-advances `current.json` from
196
- * `next_seq = N` to `next_seq = N + inputs.length` with
197
- * `If-Match`.
198
- *
199
- * NO retry on CAS loss. On `current.json` 412, throws
200
- * `BaerlyError{code:"Conflict"}` immediately — the caller (here:
201
- * `Db.transaction`) decides whether to retry by re-running the
202
- * body, or to surface to the app. Likewise on a log-entry 412
203
- * (a peer wrote our seq).
241
+ * One full commit attempt — the body of {@link commit}. Reads
242
+ * `current.json`, PUTs content + additive index `newKeys` in parallel,
243
+ * then forward-probes the tail and creates `log/<seq>` once via
244
+ * `If-None-Match: "*"` — the numbered log create IS the commit
245
+ * (single-write commit; no `current.json` CAS follows it). Stale index
246
+ * keys are DELETE'd after the commit. Returns the success payload.
204
247
  *
205
- * Empty `inputs`: returns `{ entries: [], currentEtag: undefined }`
206
- * after zero storage operations.
248
+ * Called only as `#singleAttemptCommit([input], …)`: the array shape
249
+ * is retained dead-generality (D1.5), but every call commits exactly
250
+ * one entry.
207
251
  *
208
- * @throws BaerlyError code="Conflict" — CAS lost on `current.json`,
209
- * or a log entry already exists at our seq (peer wrote ahead).
210
- * @throws BaerlyError code="Conflict" — the writer fence
211
- * (`current.json.writer_fence.epoch`) was bumped by a concurrent
212
- * `claimWriter` call between this batch's read of
213
- * `current.json` and its CAS-advance. The stale writer aborts
214
- * to honour the new authority — the kernel does NOT retry under
215
- * the old epoch. See {@link claimWriter} for the rotation
216
- * recipe.
217
- * @throws BaerlyError code="Internal" — protocol-invariant violation
218
- * (missing log entry inside `[0, next_seq)`).
219
- * @throws BaerlyError code="InvalidResponse" — malformed log body.
252
+ * A log-create 412 is disambiguated by session read-back: own session
253
+ * / own seq ⇒ our crashed-or-lost-ack commit is already durable ⇒
254
+ * adopt; foreign session ⇒ re-probe forward and retry at the next
255
+ * empty slot. Thrown `BaerlyError`s (Internal, InvalidResponse,
256
+ * NetworkError) propagate.
220
257
  *
221
- * **Implicit provisioning.** Like {@link commit}, this path auto-
222
- * creates `current.json` with a zero-state manifest on a missing
223
- * read. Because `commitBatch` does NOT retry on CAS loss, a peer
224
- * racing the same first-write surfaces `Conflict` to the caller
225
- * (`Db.transaction` re-runs the body); the manifest is durable
226
- * regardless of which writer won the create.
258
+ * Crash safety invariant: content + additive index `newKeys` PUTs are
259
+ * awaited before the log create. A crash before the create leaves
260
+ * orphan content + additive index keys (no log entry references them)
261
+ * — the compactor sweeps the content, and a stray additive key only
262
+ * yields a false-positive candidate that `matchesWire` drops. A crash
263
+ * AFTER the create is a durable, committed write at `seq` whose index
264
+ * `newKeys` are already present (so it's index-findable); the only
265
+ * residual is a possibly-undeleted stale OLD-value key, dropped by
266
+ * `matchesWire` and cleaned by a later write / `rebuild-index`. The
267
+ * inverse — committed log entry with missing content, or a de-indexed
268
+ * committed doc — is never produced.
227
269
  */
228
- async commitBatch(inputs) {
229
- if (inputs.length === 0) return {
230
- entries: [],
231
- currentEtag: void 0
232
- };
233
- const session = uuid().slice(0, 6);
234
- const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
235
- const success = await this.#singleAttemptCommit(inputs, session, logPrefix, "Writer.commitBatch", false);
236
- await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer.commitBatch");
237
- this.#emitWriteMetrics(inputs[0].collection, success.classAOps);
238
- return {
239
- entries: success.entries,
240
- currentEtag: success.currentEtag
241
- };
242
- }
243
- /**
244
- * One full commit attempt — the shared body of {@link commit} and
245
- * {@link commitBatch}. Reads `current.json`, walks the log, mints N
246
- * entries, PUTs content + indexes in parallel, PUTs log entries,
247
- * CAS-advances `current.json`. Returns the success payload + the
248
- * pre-commit fence epoch so the caller can run
249
- * {@link #verifyFenceUnchanged} outside the retry-catch arm.
250
- *
251
- * Retryable failures (a peer wrote our seq; a peer won the CAS on
252
- * `current.json`) throw `BaerlyError{code:"Conflict"}`. The caller
253
- * catches via {@link isPreconditionFailed} and either retries
254
- * (`commit`) or surfaces (`commitBatch`). Fence-bump and protocol-
255
- * invariant violations are NOT thrown from this helper — the fence
256
- * check lives in the caller so its `Conflict` propagates past the
257
- * retry-catch arm. Other thrown `BaerlyError`s (Internal,
258
- * InvalidResponse, NetworkError) bypass `isPreconditionFailed` and
259
- * propagate naturally.
260
- *
261
- * Crash safety invariant: content / index PUTs are awaited before
262
- * log PUTs, which are awaited before the CAS. A crashed mid-attempt
263
- * writer leaves orphan content / index entries (no log entry
264
- * references them) — the compactor sweeps the orphans. The
265
- * inverse — orphan log entry with missing content — is never
266
- * produced.
267
- */
268
- async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix, adoptOwnSessionOnLogConflict) {
270
+ async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix) {
269
271
  const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
270
272
  const current = read.json;
271
273
  const baseEtag = read.etag;
272
- const expectedEpoch = current.writer_fence.epoch;
273
- if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.next_seq);
274
+ if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.tail_hint);
275
+ const probeFloor = Math.max(logSeqStartOf(current), current.tail_hint);
276
+ const preCommitTail = await findLogTail(this.#storage, logPrefix, probeFloor);
277
+ let seq = preCommitTail;
274
278
  const commitNowMs = Date.now();
275
279
  const commitTs = new Date(commitNowMs).toISOString();
276
280
  const lsnTimestamp = timestamp(commitNowMs);
277
- const entries = [];
278
- for (let i = 0; i < inputs.length; i++) {
279
- const input = inputs[i];
280
- const seq = current.next_seq + i;
281
- const entry = {
282
- lsn: `${lsnTimestamp}_${session}_${countKey(seq)}`,
283
- commit_ts: commitTs,
284
- op: input.op,
285
- collection: input.collection,
286
- doc_id: input.docId,
287
- session,
288
- seq,
289
- ...input.op !== "D" && input.body !== void 0 ? { after: input.body } : {},
290
- ...input.origin !== void 0 ? { origin: input.origin } : {}
291
- };
292
- entries.push(entry);
293
- }
281
+ const input0 = inputs[0];
282
+ const mintEntry = (atSeq) => ({
283
+ lsn: `${lsnTimestamp}_${session}_${countKey(atSeq)}`,
284
+ commit_ts: commitTs,
285
+ op: input0.op,
286
+ collection: input0.collection,
287
+ doc_id: input0.docId,
288
+ session,
289
+ seq: atSeq,
290
+ ...input0.op !== "D" && input0.body !== void 0 ? { after: input0.body } : {},
291
+ ...input0.origin !== void 0 ? { origin: input0.origin } : {}
292
+ });
293
+ let entry = mintEntry(seq);
294
294
  let contentPutCount = 0;
295
- let indexClassA = 0;
295
+ let newKeysClassA = 0;
296
296
  const parallelPuts = [];
297
- const inBatchImage = /* @__PURE__ */ new Map();
298
297
  for (const input of inputs) {
299
298
  if (input.op !== "D" && input.body !== void 0) {
300
299
  contentPutCount++;
301
300
  const bytes = encodeJsonBytes(input.body);
302
301
  const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
302
+ assertKeyWithinLimit(contentKey);
303
303
  parallelPuts.push(this.#storage.put(contentKey, bytes, {
304
304
  ifNoneMatch: "*",
305
305
  contentType: APPLICATION_JSON
@@ -309,140 +309,94 @@ var Writer = class {
309
309
  throw error;
310
310
  }));
311
311
  }
312
- if (this.#indexes.length > 0) {
313
- let newKeys = [];
314
- let staleKeys = [];
315
- if (input.op === "I") newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
316
- else if (input.op === "U") {
317
- const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
318
- const oldKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
319
- newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
320
- const newSet = new Set(newKeys);
321
- staleKeys = oldKeys.filter((k) => !newSet.has(k));
322
- } else {
323
- const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
324
- staleKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
312
+ if (this.#indexes.length > 0 && input.op !== "D") {
313
+ const newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
314
+ for (const k of newKeys) {
315
+ assertKeyWithinLimit(k);
316
+ newKeysClassA++;
317
+ parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
318
+ ifNoneMatch: "*",
319
+ contentType: APPLICATION_JSON
320
+ }).catch((error) => {
321
+ this.#observe429(error, input.collection);
322
+ if (isPreconditionFailed(error)) return;
323
+ throw error;
324
+ }));
325
325
  }
326
- for (const k of newKeys) parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
327
- ifNoneMatch: "*",
328
- contentType: APPLICATION_JSON
329
- }).catch((error) => {
330
- this.#observe429(error, input.collection);
331
- if (isPreconditionFailed(error)) return;
332
- throw error;
333
- }));
334
- for (const k of staleKeys) parallelPuts.push(this.#storage.delete(k));
335
- indexClassA += newKeys.length + staleKeys.length;
336
- if (newKeys.length + staleKeys.length > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", newKeys.length + staleKeys.length, { collection: input.collection });
337
- inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
338
326
  }
339
327
  }
340
328
  await Promise.all(parallelPuts);
341
- const logPutOne = async (entry) => {
342
- const logEntryKey = `${logPrefix}/log/${entry.seq}.json`;
343
- const logBytes = encodeJsonBytes(entry);
329
+ let committedEntry = entry;
330
+ let probes = 0;
331
+ let transientRetries = 0;
332
+ for (;;) {
333
+ const logEntryKey = logObjectKey(logPrefix, seq);
334
+ assertKeyWithinLimit(logEntryKey);
335
+ let conflicted = false;
344
336
  try {
345
- await this.#storage.put(logEntryKey, logBytes, {
337
+ await this.#storage.put(logEntryKey, encodeJsonBytes(entry), {
346
338
  ifNoneMatch: "*",
347
339
  contentType: APPLICATION_JSON
348
340
  });
349
- return { ok: true };
350
341
  } catch (error) {
351
342
  this.#observe429(error, entry.collection);
352
- if (!isPreconditionFailed(error)) throw error;
353
- ctxMetrics().counter("db.r2.put.412_total", 1, {
354
- collection: entry.collection,
355
- step: "log-put"
356
- });
357
- return { ok: false };
343
+ if (isPreconditionFailed(error)) {
344
+ ctxMetrics().counter("db.r2.put.412_total", 1, {
345
+ collection: entry.collection,
346
+ step: "log-put"
347
+ });
348
+ conflicted = true;
349
+ } else if (isTransientWrite(error) && transientRetries < this.#maxRetries) {
350
+ transientRetries++;
351
+ await this.#backoff(transientRetries);
352
+ continue;
353
+ } else throw error;
358
354
  }
359
- };
360
- const logPutResults = await Promise.all(entries.map(logPutOne));
361
- let committedEntries = entries;
362
- const firstConflictIdx = logPutResults.findIndex((r) => !r.ok);
363
- if (firstConflictIdx !== -1) {
364
- const conflictedEntry = entries[firstConflictIdx];
365
- const logEntryKey = `${logPrefix}/log/${conflictedEntry.seq}.json`;
366
- if (adoptOwnSessionOnLogConflict) {
367
- const decision = tryAdoptOwnSessionLogEntry({
368
- self: conflictedEntry,
369
- existing: await readLogEntry(this.#storage, logEntryKey),
370
- batchSize: inputs.length
371
- });
372
- if (decision.adopt) committedEntries = [decision.entry];
373
- else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; ${decision.reason}`);
374
- } else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; peer wrote our seq`);
375
- }
376
- const batchLogBytes = committedEntries.reduce((sum, e) => sum + encodeJsonBytes(e).byteLength, 0);
377
- const next = {
378
- ...current,
379
- next_seq: current.next_seq + inputs.length,
380
- tail_bytes: current.tail_bytes + batchLogBytes
381
- };
382
- 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}`);
383
- const nextBody = encodeJsonBytes(next);
384
- const putOpts = {
385
- ifMatch: baseEtag,
386
- contentType: APPLICATION_JSON
387
- };
388
- let result;
389
- try {
390
- result = await this.#storage.put(this.#currentJsonKey, nextBody, putOpts);
391
- } catch (error) {
392
- this.#observe429(error, inputs[0].collection);
393
- if (isPreconditionFailed(error)) {
394
- ctxMetrics().counter("db.r2.put.412_total", 1, {
395
- collection: inputs[0].collection,
396
- step: "current-json-cas"
397
- });
398
- throw new BaerlyError("Conflict", `${errorPrefix}: CAS conflict on ${this.#currentJsonKey}`);
355
+ if (!conflicted) {
356
+ committedEntry = entry;
357
+ break;
358
+ }
359
+ const existing = await readLogEntry(this.#storage, logEntryKey);
360
+ const decision = tryAdoptOwnSessionLogEntry({
361
+ self: entry,
362
+ existing,
363
+ batchSize: inputs.length
364
+ });
365
+ if (decision.adopt) {
366
+ committedEntry = decision.entry;
367
+ break;
399
368
  }
400
- throw error;
369
+ if (++probes > 1e5) throw new BaerlyError("Internal", `${errorPrefix}: log-tail forward-probe exceeded ${LOG_FORWARD_PROBE_CAP} on ${this.#currentJsonKey}`);
370
+ seq = await findLogTail(this.#storage, logPrefix, seq + 1);
371
+ entry = mintEntry(seq);
401
372
  }
402
- const prevSeq = current.next_seq;
373
+ const committedEntries = [committedEntry];
374
+ const staleKeysClassA = await this.#cleanupStaleIndexKeysBestEffort({
375
+ inputs,
376
+ logPrefix,
377
+ seq
378
+ });
379
+ const indexClassA = newKeysClassA + staleKeysClassA;
380
+ if (this.#indexes.length > 0 && indexClassA > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", indexClassA, { collection: input0.collection });
381
+ const prevSeq = preCommitTail;
382
+ const observedTail = seq + 1;
403
383
  const maint = getCurrentContext()?.maintenance;
404
- if (maint?.disabled !== true) {
405
- if (shouldFireMaintenance(next, prevSeq, maint?.options?.gcInterval ?? 4)) await (maint?.dispatch ?? dispatchInlineAwaited)(() => runBoundedMaintenance({
406
- storage: this.#storage,
407
- currentJsonKey: this.#currentJsonKey,
408
- prevSeq,
409
- ...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes }
410
- }, maint?.options).then(() => {}, () => {}));
411
- }
412
- const classAOps = contentPutCount + entries.length + indexClassA + 1;
384
+ const gcInterval = maint?.options?.profile?.gcInterval ?? MAINTENANCE_PROFILE_CF_FREE.gcInterval;
385
+ if (maint?.disabled === true ? observedTail - current.tail_hint >= 128 : shouldFireMaintenance(current, prevSeq, gcInterval, observedTail)) await (maint?.dispatch ?? dispatchInlineAwaited)(() => runBoundedMaintenance({
386
+ storage: this.#storage,
387
+ currentJsonKey: this.#currentJsonKey,
388
+ prevSeq,
389
+ observedTail,
390
+ ...maint?.disabled === true && { disabled: true },
391
+ ...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes }
392
+ }, maint?.options).then(() => {}, () => {}));
413
393
  return {
414
394
  entries: committedEntries,
415
- currentEtag: result.etag,
416
- classAOps,
417
- expectedEpoch
395
+ currentEtag: baseEtag,
396
+ classAOps: contentPutCount + 1 + indexClassA
418
397
  };
419
398
  }
420
399
  /**
421
- * Read the pre-image content body for a doc by walking the live
422
- * log backwards from `currentNextSeq` looking for the
423
- * most-recent I/U entry on this `(collection, docId)`. Returns
424
- * `undefined` when:
425
- *
426
- * - the doc's most-recent op was `D` (tombstone — no live body);
427
- * - no entry for this doc lives inside the visible log range
428
- * `[log_seq_start, currentNextSeq)` (a fresh-insert race or
429
- * the doc has been folded into the snapshot but is no longer
430
- * referenced).
431
- *
432
- * Used ONLY by the index-emission path on `U` / `D` to compute
433
- * the stale-key set. Bounded by `log_seq_start`: entries below
434
- * have been folded into the snapshot and may already be swept
435
- * off the bucket — a snapshot fold is the rebuild command's job
436
- * (see `./rebuild-index.ts`), not the writer's.
437
- *
438
- * **Cost note:** linear walk, O(snapshot lag). For day-one Phase
439
- * 8 collections (helpdesk-shape: 100s of docs, <10k log entries)
440
- * this is fine — the compactor folds the live tail every ~100
441
- * entries (`packages/server/src/compactor.ts`). A follow-up ticket
442
- * caches per-doc index head in `current.json` for O(1) lookup.
443
- * The bound is documented; out of scope here.
444
- */
445
- /**
446
400
  * Auto-create the per-collection `current.json` at
447
401
  * `this.#currentJsonKey` with a zero-state initial manifest. Called
448
402
  * by `#singleAttemptCommit` when the read returned `null` (fresh
@@ -454,7 +408,7 @@ var Writer = class {
454
408
  * the create — a single recover-via-read covers every race that
455
409
  * could have produced our null read.
456
410
  *
457
- * The seed shape (`snapshot: null`, `next_seq: 0`, `log_seq_start:
411
+ * The seed shape (`snapshot: null`, `tail_hint: 0`, `log_seq_start:
458
412
  * 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
459
413
  * matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
460
414
  * operator who pre-provisions and a writer who auto-creates land
@@ -466,16 +420,15 @@ var Writer = class {
466
420
  */
467
421
  async #provisionCurrentJson() {
468
422
  const initial = {
469
- schema_version: 2,
423
+ schema_version: 3,
470
424
  snapshot: null,
471
- next_seq: 0,
425
+ tail_hint: 0,
472
426
  log_seq_start: 0,
473
427
  writer_fence: {
474
428
  epoch: 0,
475
429
  owner: "",
476
430
  claimed_at: ""
477
431
  },
478
- tail_bytes: 0,
479
432
  snapshot_bytes: 0,
480
433
  snapshot_rows: 0
481
434
  };
@@ -488,9 +441,69 @@ var Writer = class {
488
441
  if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
489
442
  return recovered;
490
443
  }
444
+ async #cleanupStaleIndexKeysBestEffort(args) {
445
+ if (this.#indexes.length === 0) return 0;
446
+ let staleKeysClassA = 0;
447
+ const indexDeletes = [];
448
+ const inBatchImage = /* @__PURE__ */ new Map();
449
+ for (const input of args.inputs) {
450
+ let staleKeys = [];
451
+ try {
452
+ if (input.op === "U") {
453
+ const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(args.logPrefix, input.collection, input.docId, args.seq);
454
+ const oldKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);
455
+ const newSet = new Set(allIndexKeysFor(args.logPrefix, this.#indexes, input.body, input.docId));
456
+ staleKeys = oldKeys.filter((k) => !newSet.has(k));
457
+ } else if (input.op === "D") {
458
+ const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(args.logPrefix, input.collection, input.docId, args.seq);
459
+ staleKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);
460
+ }
461
+ } catch {
462
+ ctxMetrics().counter("db.write.index_cleanup_errors_total", 1, {
463
+ collection: input.collection,
464
+ step: "pre-image-read"
465
+ });
466
+ inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
467
+ continue;
468
+ }
469
+ for (const k of staleKeys) indexDeletes.push(this.#storage.delete(k).catch(() => {
470
+ ctxMetrics().counter("db.write.index_cleanup_errors_total", 1, {
471
+ collection: input.collection,
472
+ step: "delete"
473
+ });
474
+ }));
475
+ staleKeysClassA += staleKeys.length;
476
+ inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
477
+ }
478
+ await Promise.all(indexDeletes);
479
+ return staleKeysClassA;
480
+ }
481
+ /**
482
+ * Read the pre-image content body for a doc by walking the live log
483
+ * backwards from `currentNextSeq` looking for the most-recent I/U
484
+ * entry on this `(collection, docId)`. Returns `undefined` when:
485
+ *
486
+ * - the doc's most-recent op was `D` (tombstone — no live body);
487
+ * - no entry for this doc lives inside the visible log range
488
+ * `[log_seq_start, currentNextSeq)` (a fresh-insert race or the
489
+ * doc has been folded into the snapshot but is no longer
490
+ * referenced).
491
+ *
492
+ * Used ONLY by the index-emission path's stale-key half (Step 5b, on
493
+ * `U` / `D`) to compute which OLD-value keys to DELETE. Bounded by
494
+ * `log_seq_start`: entries below have been folded into the snapshot
495
+ * and may already be swept off the bucket — a snapshot fold is the
496
+ * rebuild command's job (see `./rebuild-index.ts`), not the writer's.
497
+ *
498
+ * **Cost note:** linear walk, O(snapshot lag). For helpdesk-shape
499
+ * collections (100s of docs, <10k log entries) this is fine — the
500
+ * compactor folds the live tail every ~100 entries
501
+ * (`packages/server/src/compactor.ts`). A follow-up ticket caches
502
+ * per-doc index head in `current.json` for O(1) lookup.
503
+ */
491
504
  async #readPreImage(logPrefix, collection, docId, currentNextSeq) {
492
505
  for (let s = currentNextSeq - 1; s >= 0; s--) {
493
- const logKey = `${logPrefix}/log/${s}.json`;
506
+ const logKey = logObjectKey(logPrefix, s);
494
507
  const got = await this.#storage.get(logKey);
495
508
  if (got === null) continue;
496
509
  let entry;
@@ -535,32 +548,14 @@ var Writer = class {
535
548
  }
536
549
  /**
537
550
  * Emit the per-logical-write `class_a_ops_per_logical_write`
538
- * histogram shared by `commit` and `commitBatch`. `classAOps`
539
- * differs between the two paths (retry-budget vs batch shape),
540
- * so each caller computes it.
551
+ * histogram for `commit`. `classAOps` is the per-attempt base plus
552
+ * a charge for prior failed attempts (the retry-budget cost model),
553
+ * computed by the caller.
541
554
  */
542
555
  #emitWriteMetrics(collection, classAOps) {
543
556
  ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
544
557
  }
545
558
  /**
546
- * Re-read `current.json` after a successful CAS and assert the
547
- * writer-fence epoch is still ours. The CAS only mutated `next_seq`
548
- * (the fence is preserved from `current`), so a post-write epoch
549
- * mismatch can only mean another writer claimed the fence between
550
- * our step-1 read and step-6 PUT — the exact split-brain
551
- * `WriterFence` prevents. Throws `Conflict`; no retry, since the
552
- * stale writer must defer to the new authority.
553
- *
554
- * The fence-verify GET is Class B and intentionally NOT counted in
555
- * `class_a_ops_per_logical_write`.
556
- */
557
- async #verifyFenceUnchanged(expectedEpoch, where) {
558
- const postRead = await readCurrentJson(this.#storage, this.#currentJsonKey);
559
- if (postRead === null) return;
560
- if (postRead.json.writer_fence.epoch === expectedEpoch) return;
561
- 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`);
562
- }
563
- /**
564
559
  * Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
565
560
  * at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
566
561
  * from re-racing in lockstep. Worst-case total wait across the
@@ -580,6 +575,13 @@ var Writer = class {
580
575
  */
581
576
  const isPreconditionFailed = (err) => err instanceof BaerlyError && err.code === "Conflict";
582
577
  /**
578
+ * `true` when a log-create PUT failed transiently (a `NetworkError`) —
579
+ * the write may or may not have landed (a dropped ack). Safe to retry
580
+ * the SAME seq: own-session adoption closes the double-commit window if
581
+ * it did land. NOT a 412 (that's handled by adoption directly).
582
+ */
583
+ const isTransientWrite = (err) => err instanceof BaerlyError && err.code === "NetworkError";
584
+ /**
583
585
  * `true` when the underlying storage surfaced an R2 prefix-partition
584
586
  * rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
585
587
  * onto `BaerlyError.cause` as `{ status }`; we discriminate on that
@@ -600,22 +602,25 @@ const is429 = (err) => {
600
602
  * integration test) can divert the input by passing
601
603
  * `{ streams: { stdin } }` to {@link runRestore}. Idempotent on a fresh
602
604
  * bucket: re-running on a half-completed restore **refuses** unless
603
- * `--force` is set (which bumps the writer fence and seeds a fresh
604
- * `current.json` first).
605
+ * `--force` is set (which reseeds a fresh `current.json` above the old
606
+ * tail first).
605
607
  *
606
608
  * Args:
607
609
  * --bucket Required. Target bucket URI.
608
610
  * --app Required (or via baerly.config.ts).
609
611
  * --tenant Required (or via baerly.config.ts).
610
612
  * --collection Required. Target collection name.
611
- * --force Truncate the target if it exists (fence-bump + reseed).
613
+ * --force Truncate the target if it exists (reseed above the old tail).
612
614
  * --json JSON envelope.
613
615
  *
614
616
  * stdin: NDJSON, one `{_id, ...}` row per line. Empty lines tolerated.
615
617
  * EOF terminates.
616
618
  *
617
- * Cost shape: 1 PUT current.json (initial) + N × (1 PUT log + 1 PUT
618
- * content + 1 PUT current.json CAS) = 3N + 1 Class A ops for N rows.
619
+ * Cost shape: under single-write commit each `Writer.commit` is 2 Class
620
+ * A PUTs (content + the committing `log/<seq>` create — no per-row
621
+ * `current.json` write). So: 1 PUT current.json (initial seed) + N × 2
622
+ * + 1 PUT current.json (final `tail_hint` stamp) = 2N + 2 Class A ops
623
+ * for N rows.
619
624
  *
620
625
  * Partial-restore semantics: a mid-stream Network / Internal / parse
621
626
  * error leaves the target in a partial state (some rows committed,
@@ -633,65 +638,81 @@ const is429 = (err) => {
633
638
  * concurrent writer when --force was used.
634
639
  */
635
640
  const RESTORE_OWNER = "baerly-restore";
641
+ const RESTORE_ARGS = {
642
+ bucket: {
643
+ type: "string",
644
+ required: true,
645
+ description: "Target bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)",
646
+ valueHint: "bucket-uri"
647
+ },
648
+ app: {
649
+ type: "string",
650
+ required: false,
651
+ description: "Application name segment (defaults to baerly.config.ts).",
652
+ valueHint: "app"
653
+ },
654
+ tenant: {
655
+ type: "string",
656
+ required: false,
657
+ description: "Tenant name segment (defaults to baerly.config.ts).",
658
+ valueHint: "tenant"
659
+ },
660
+ collection: {
661
+ type: "string",
662
+ required: true,
663
+ description: "Target collection name.",
664
+ valueHint: "name"
665
+ },
666
+ force: {
667
+ type: "boolean",
668
+ description: "Truncate the target if it exists (bump fence + reseed current.json)."
669
+ },
670
+ json: {
671
+ type: "boolean",
672
+ description: "Emit a structured JSON envelope to stdout (success) or stderr (error)"
673
+ }
674
+ };
675
+ const tailFromListedLogKeys = async (storage, collectionPrefix) => {
676
+ const logPrefix = `${collectionPrefix}/log/`;
677
+ let maxSeq = -1;
678
+ for await (const entry of storage.list(logPrefix)) {
679
+ const tail = entry.key.slice(logPrefix.length);
680
+ const match = /^(\d+)\.json$/.exec(tail);
681
+ if (match === null) continue;
682
+ const seq = Number.parseInt(match[1], 10);
683
+ if (Number.isFinite(seq) && seq > maxSeq) maxSeq = seq;
684
+ }
685
+ return maxSeq + 1;
686
+ };
636
687
  const bundle = defineBaerlySubcommand({
637
688
  name: "admin.restore",
638
689
  meta: { description: "Bulk-import canonical NDJSON into a fresh collection." },
639
- args: {
640
- bucket: {
641
- type: "string",
642
- required: true,
643
- description: "Target bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)",
644
- valueHint: "bucket-uri"
645
- },
646
- app: {
647
- type: "string",
648
- required: false,
649
- description: "Application name segment (defaults to baerly.config.ts).",
650
- valueHint: "app"
651
- },
652
- tenant: {
653
- type: "string",
654
- required: false,
655
- description: "Tenant name segment (defaults to baerly.config.ts).",
656
- valueHint: "tenant"
657
- },
658
- collection: {
659
- type: "string",
660
- required: true,
661
- description: "Target collection name.",
662
- valueHint: "name"
663
- },
664
- force: {
665
- type: "boolean",
666
- description: "Truncate the target if it exists (bump fence + reseed current.json)."
667
- },
668
- json: {
669
- type: "boolean",
670
- description: "Emit a structured JSON envelope to stdout (success) or stderr (error)"
671
- }
672
- },
690
+ args: RESTORE_ARGS,
673
691
  handler: async (args, ctx) => {
674
692
  const bucket = await parseBucketUri(args.bucket);
675
693
  const { app, tenant } = await ctx.resolveAppTenant({
676
694
  app: args.app,
677
695
  tenant: args.tenant
678
696
  });
697
+ assertCollectionArg(args.collection, "baerly admin restore");
679
698
  const currentJsonKey = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}/current.json`;
699
+ let baseSeq = 0;
680
700
  const head = await readCurrentJson(bucket.storage, currentJsonKey);
681
701
  if (head !== null && args.force !== true) throw new BaerlyError("Conflict", `baerly admin restore: ${currentJsonKey} exists; pass --force to truncate`);
682
702
  if (head !== null) {
683
- const truncatedNext = head.json.next_seq;
703
+ const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf("/"));
704
+ const truncatedNext = await tailFromListedLogKeys(bucket.storage, collectionPrefix);
705
+ baseSeq = truncatedNext;
684
706
  const reseeded = {
685
- schema_version: 2,
707
+ schema_version: 3,
686
708
  snapshot: null,
687
- next_seq: truncatedNext,
709
+ tail_hint: truncatedNext,
688
710
  log_seq_start: truncatedNext,
689
711
  writer_fence: {
690
712
  epoch: head.json.writer_fence.epoch + 1,
691
713
  owner: RESTORE_OWNER,
692
714
  claimed_at: ""
693
715
  },
694
- tail_bytes: 0,
695
716
  snapshot_bytes: 0,
696
717
  snapshot_rows: 0
697
718
  };
@@ -706,16 +727,15 @@ const bundle = defineBaerlySubcommand({
706
727
  }
707
728
  } else {
708
729
  const seed = {
709
- schema_version: 2,
730
+ schema_version: 3,
710
731
  snapshot: null,
711
- next_seq: 0,
732
+ tail_hint: 0,
712
733
  log_seq_start: 0,
713
734
  writer_fence: {
714
735
  epoch: 0,
715
736
  owner: RESTORE_OWNER,
716
737
  claimed_at: ""
717
738
  },
718
- tail_bytes: 0,
719
739
  snapshot_bytes: 0,
720
740
  snapshot_rows: 0
721
741
  };
@@ -753,6 +773,20 @@ const bundle = defineBaerlySubcommand({
753
773
  });
754
774
  count++;
755
775
  }
776
+ if (count > 0) {
777
+ const afterLoad = await readCurrentJson(bucket.storage, currentJsonKey);
778
+ if (afterLoad !== null) {
779
+ const clampedTail = Math.max(baseSeq + count, afterLoad.json.tail_hint, afterLoad.json.log_seq_start);
780
+ const stamped = {
781
+ ...afterLoad.json,
782
+ tail_hint: clampedTail
783
+ };
784
+ await bucket.storage.put(currentJsonKey, encodeJsonBytes(stamped), {
785
+ ifMatch: afterLoad.etag,
786
+ contentType: "application/json"
787
+ });
788
+ }
789
+ }
756
790
  emitSuccess({
757
791
  command: "admin.restore",
758
792
  status: "ok",
@@ -768,4 +802,4 @@ bundle.run;
768
802
  //#endregion
769
803
  export { restoreCmd };
770
804
 
771
- //# sourceMappingURL=restore-C6IcmLeA.js.map
805
+ //# sourceMappingURL=restore-DpQYef6r.js.map