@gusto/baerly-storage 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. package/README.md +47 -124
  2. package/dist/API.md +161 -511
  3. package/dist/CHANGELOG.md +1148 -307
  4. package/dist/RECIPES.md +398 -80
  5. package/dist/THIRD-PARTY-LICENSES.txt +5 -26
  6. package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
  7. package/dist/app-config.d.ts +31 -1
  8. package/dist/app-config.js +1 -2
  9. package/dist/app-config.js.map +1 -1
  10. package/dist/auth.d.ts +33 -28
  11. package/dist/auth.js +549 -985
  12. package/dist/auth.js.map +1 -1
  13. package/dist/baerly.js +130 -138
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +97 -22
  16. package/dist/capacity-warning-header-BlVopyiI.js +16 -0
  17. package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
  18. package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
  19. package/dist/client-react.d.ts +67 -20
  20. package/dist/client-react.js +240 -54
  21. package/dist/client-react.js.map +1 -1
  22. package/dist/client.d.ts +5 -4
  23. package/dist/client.js +51 -16
  24. package/dist/client.js.map +1 -1
  25. package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
  26. package/dist/cloudflare-CKHYXccw.js.map +1 -0
  27. package/dist/cloudflare.d.ts +106 -71
  28. package/dist/cloudflare.js +334 -271
  29. package/dist/cloudflare.js.map +1 -1
  30. package/dist/code-resolution-CL_7L0wS.js +22 -0
  31. package/dist/code-resolution-CL_7L0wS.js.map +1 -0
  32. package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
  33. package/dist/config-DEzInG6M.js +4035 -0
  34. package/dist/config-DEzInG6M.js.map +1 -0
  35. package/dist/constants-D3GSH3tc.js +469 -0
  36. package/dist/constants-D3GSH3tc.js.map +1 -0
  37. package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
  38. package/dist/context-rlpSnHFA.js.map +1 -0
  39. package/dist/cost-B52llVDx.js +330 -0
  40. package/dist/cost-B52llVDx.js.map +1 -0
  41. package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
  42. package/dist/current-json-CC6lE4Aj.js.map +1 -0
  43. package/dist/db-plFUNTSF.d.ts +130 -0
  44. package/dist/db-read-seams-BSs0m1z1.js +3261 -0
  45. package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
  46. package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
  47. package/dist/deploy-Obj4nE-Z.js.map +1 -0
  48. package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
  49. package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
  50. package/dist/dev-landing-CD-si4dW.js +50 -0
  51. package/dist/dev-landing-CD-si4dW.js.map +1 -0
  52. package/dist/dev-vite.d.ts +38 -39
  53. package/dist/dev-vite.js +67 -36
  54. package/dist/dev-vite.js.map +1 -1
  55. package/dist/dev.d.ts +3 -2
  56. package/dist/dev.js +2 -1
  57. package/dist/doctor-BA0i-YAN.js +270 -0
  58. package/dist/doctor-BA0i-YAN.js.map +1 -0
  59. package/dist/dump-D1vX8ozg.js +133 -0
  60. package/dist/dump-D1vX8ozg.js.map +1 -0
  61. package/dist/errors-7Rk1HGCE.js +160 -0
  62. package/dist/errors-7Rk1HGCE.js.map +1 -0
  63. package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
  64. package/dist/export-BVL2EvYE.js.map +1 -0
  65. package/dist/fsck-BWkPgov4.js +145 -0
  66. package/dist/fsck-BWkPgov4.js.map +1 -0
  67. package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
  68. package/dist/gcs.d.ts +30 -0
  69. package/dist/gcs.js +1 -0
  70. package/dist/goog4-signer-CeLIABoE.js +331 -0
  71. package/dist/goog4-signer-CeLIABoE.js.map +1 -0
  72. package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
  73. package/dist/http-Z5rZyYMX.js.map +1 -0
  74. package/dist/http-transport-DNUM8kU-.js +1299 -0
  75. package/dist/http-transport-DNUM8kU-.js.map +1 -0
  76. package/dist/http.d.ts +366 -294
  77. package/dist/http.js +2 -2
  78. package/dist/index-JJrIu1pO.d.ts +135 -0
  79. package/dist/index-LEgHN0qJ.d.ts +50 -0
  80. package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
  81. package/dist/index.d.ts +27 -6
  82. package/dist/index.js +3 -5
  83. package/dist/inspect-BTsVYZKd.js +196 -0
  84. package/dist/inspect-BTsVYZKd.js.map +1 -0
  85. package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
  86. package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
  87. package/dist/ledger-Dj_bGgo0.js +192 -0
  88. package/dist/ledger-Dj_bGgo0.js.map +1 -0
  89. package/dist/legacy-names-DgZBtgOh.js +47 -0
  90. package/dist/legacy-names-DgZBtgOh.js.map +1 -0
  91. package/dist/log-C9W15Dfo.d.ts +94 -0
  92. package/dist/log-tail-DWJbneBF.js +142 -0
  93. package/dist/log-tail-DWJbneBF.js.map +1 -0
  94. package/dist/log-walk-C-vA-WGJ.js +111 -0
  95. package/dist/log-walk-C-vA-WGJ.js.map +1 -0
  96. package/dist/maintenance-Dd-Yakqj.js +1709 -0
  97. package/dist/maintenance-Dd-Yakqj.js.map +1 -0
  98. package/dist/maintenance-DevB6z4e.js +2237 -0
  99. package/dist/maintenance-DevB6z4e.js.map +1 -0
  100. package/dist/maintenance.d.ts +100 -3
  101. package/dist/maintenance.js +1 -3
  102. package/dist/node.d.ts +130 -142
  103. package/dist/node.js +4 -3
  104. package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
  105. package/dist/observability-C-ISCCLE.js.map +1 -0
  106. package/dist/observability.d.ts +27 -3
  107. package/dist/observability.js +3 -3
  108. package/dist/path-segment-DBXG26PW.js +363 -0
  109. package/dist/path-segment-DBXG26PW.js.map +1 -0
  110. package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
  111. package/dist/plan-BvQbaNMe.js.map +1 -0
  112. package/dist/request-CRWiTrza.js +272 -0
  113. package/dist/request-CRWiTrza.js.map +1 -0
  114. package/dist/restore-U6Im8V1V.js +1467 -0
  115. package/dist/restore-U6Im8V1V.js.map +1 -0
  116. package/dist/retry-OBtLB2GC.js +126 -0
  117. package/dist/retry-OBtLB2GC.js.map +1 -0
  118. package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
  119. package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
  120. package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
  121. package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
  122. package/dist/s3.d.ts +20 -7
  123. package/dist/s3.js +4 -5
  124. package/dist/s3.js.map +1 -1
  125. package/dist/sha256-4FfGQNPw.js +22 -0
  126. package/dist/sha256-4FfGQNPw.js.map +1 -0
  127. package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
  128. package/dist/shared-secret-Vkur-8r0.js.map +1 -0
  129. package/dist/sigv4-sign-5IUflUD_.js +507 -0
  130. package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
  131. package/dist/snapshot-CknzkDM0.js +148 -0
  132. package/dist/snapshot-CknzkDM0.js.map +1 -0
  133. package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
  134. package/dist/src-Actga-bO.js.map +1 -0
  135. package/dist/src-D0MQfvOp.js +812 -0
  136. package/dist/src-D0MQfvOp.js.map +1 -0
  137. package/dist/src-Dr9uo3dc.js +501 -0
  138. package/dist/src-Dr9uo3dc.js.map +1 -0
  139. package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
  140. package/dist/subcommand-BLoF66dG.js.map +1 -0
  141. package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
  142. package/dist/time-DRxTP9iv.js.map +1 -0
  143. package/dist/types-suVbsEWS.d.ts +116 -0
  144. package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
  145. package/dist/usage-CPzVhrQr.js.map +1 -0
  146. package/dist/uuid-BuT_c404.js +333 -0
  147. package/dist/uuid-BuT_c404.js.map +1 -0
  148. package/dist/verifier-Bmlmndzo.d.ts +95 -0
  149. package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
  150. package/dist/wire-DndvKU-K.js.map +1 -0
  151. package/package.json +96 -69
  152. package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
  153. package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
  154. package/dist/bytes-BXdamO3L.js +0 -11
  155. package/dist/bytes-BXdamO3L.js.map +0 -1
  156. package/dist/cloudflare-DzKBrUlg.js.map +0 -1
  157. package/dist/config-1tv0-Yzm.js +0 -2693
  158. package/dist/config-1tv0-Yzm.js.map +0 -1
  159. package/dist/constants-CfeMWQWk.js +0 -222
  160. package/dist/constants-CfeMWQWk.js.map +0 -1
  161. package/dist/context-DRZ3tZ5l.js.map +0 -1
  162. package/dist/cost-DSMIVqzL.js +0 -203
  163. package/dist/cost-DSMIVqzL.js.map +0 -1
  164. package/dist/current-json-C6nhPOm1.js.map +0 -1
  165. package/dist/db-DsPkOVEH.d.ts +0 -254
  166. package/dist/deploy-DonTr-CV.js.map +0 -1
  167. package/dist/doctor-DSIyCDg_.js +0 -346
  168. package/dist/doctor-DSIyCDg_.js.map +0 -1
  169. package/dist/dump-Bh5k26VQ.js +0 -94
  170. package/dist/dump-Bh5k26VQ.js.map +0 -1
  171. package/dist/errors-Dfa3p78c.js +0 -78
  172. package/dist/errors-Dfa3p78c.js.map +0 -1
  173. package/dist/export-DtF5tDIM.js +0 -401
  174. package/dist/export-DtF5tDIM.js.map +0 -1
  175. package/dist/fsck-D_djMO5D.js +0 -279
  176. package/dist/fsck-D_djMO5D.js.map +0 -1
  177. package/dist/http-DGd5tbNs.js.map +0 -1
  178. package/dist/index-0rZcMBwy.d.ts +0 -115
  179. package/dist/index-BNRh23K9.d.ts +0 -162
  180. package/dist/index-BYk9oCNf.d.ts +0 -1112
  181. package/dist/indexes-Dn9hbGQG.d.ts +0 -22
  182. package/dist/inspect-6WZ-pC7-.js +0 -133
  183. package/dist/inspect-6WZ-pC7-.js.map +0 -1
  184. package/dist/log-tail-D98U1JBo.js +0 -522
  185. package/dist/log-tail-D98U1JBo.js.map +0 -1
  186. package/dist/maintenance-B4Dki6Ig.js +0 -2157
  187. package/dist/maintenance-B4Dki6Ig.js.map +0 -1
  188. package/dist/maintenance-B_e0T99L.d.ts +0 -537
  189. package/dist/maintenance-C7coQp4c.js +0 -1418
  190. package/dist/maintenance-C7coQp4c.js.map +0 -1
  191. package/dist/normalize-rjnZLwS4.js +0 -133
  192. package/dist/normalize-rjnZLwS4.js.map +0 -1
  193. package/dist/observability-BmflLCdF.js.map +0 -1
  194. package/dist/plan-a7PJHBCy.js.map +0 -1
  195. package/dist/query-rAtXNQQB.js +0 -1773
  196. package/dist/query-rAtXNQQB.js.map +0 -1
  197. package/dist/rebuild-index-BVzQSZlm.js +0 -81
  198. package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
  199. package/dist/request-u0M51mhJ.js +0 -72
  200. package/dist/request-u0M51mhJ.js.map +0 -1
  201. package/dist/restore-R-4rbciV.js +0 -778
  202. package/dist/restore-R-4rbciV.js.map +0 -1
  203. package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
  204. package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
  205. package/dist/shared-secret-DgEicd3x.js.map +0 -1
  206. package/dist/src-BL_JoPTn.js.map +0 -1
  207. package/dist/src-CYHFDrKz.js +0 -536
  208. package/dist/src-CYHFDrKz.js.map +0 -1
  209. package/dist/src-DYZ4H1aF.js +0 -392
  210. package/dist/src-DYZ4H1aF.js.map +0 -1
  211. package/dist/subcommand-DoDA-K7d.js.map +0 -1
  212. package/dist/time-DUqvFMHq.js.map +0 -1
  213. package/dist/usage-DBV1eQHC.js.map +0 -1
  214. package/dist/validate-DtljsCh1.js.map +0 -1
  215. package/dist/wire-izfGZDvr.js.map +0 -1
@@ -0,0 +1,2237 @@
1
+ import { i as isWriteConflict, t as BaerlyError } from "./errors-7Rk1HGCE.js";
2
+ import { c as certifiedDeleteFloor, d as logSeqStartOf, g as encodeJsonBytes, h as decodeJsonBytes, m as unsupportedSchemaVersionMessage, o as assertCurrentJsonTransition, p as readCurrentJson, s as casUpdateCurrentJson, t as assertNameSegment, u as logDeleteFloorOf } from "./path-segment-DBXG26PW.js";
3
+ import { _ as MAINTENANCE_PROFILE_NODE, c as GC_MARK_LIST_PAGE_KEYS, d as GC_PENDING_CONTENT_TYPE, f as LOG_FORWARD_PROBE_CAP, g as MAINTENANCE_PROFILE_CF_PAID, h as MAINTENANCE_PROFILE_CF_FREE, l as GC_MAX_PENDING_CANDIDATES, m as MAINTENANCE_MIN_LIVE_BYTES, r as CF_PAID_COMPACT_TAIL_PROBE_GETS, u as GC_PASS_GRACE_FRACTION } from "./constants-D3GSH3tc.js";
4
+ import { t as sha256Hex } from "./sha256-4FfGQNPw.js";
5
+ import { r as currentRequestLedger } from "./ledger-Dj_bGgo0.js";
6
+ import { n as ctxMetrics, r as getCurrentContext } from "./context-rlpSnHFA.js";
7
+ // packages/protocol/src/coordination/gc-pending.ts
8
+ /**
9
+ * `gc/pending.json` — the per-collection GC candidate ledger. CAS-
10
+ * protected; one per `(tenant, collection)` key — for example
11
+ * `<tenant>/<collection>/gc/pending.json`. `runGc()` is the single
12
+ * writer that adds and removes entries. Stays small in steady state
13
+ * because every candidate is eventually resolved out of the ledger.
14
+ *
15
+ * "Mark" appends candidates with a future `due_at`; "sweep" revalidates
16
+ * due candidates and either DELETEs the named object or resolves the
17
+ * entry out of the ledger without one. Both run in the same GC pass, not
18
+ * separate passes.
19
+ *
20
+ * Lives next to {@link CurrentJson} in `coordination/` — same shape
21
+ * of "CAS-protected small control object." Pure module; no Node
22
+ * imports; Worker-bundleable.
23
+ *
24
+ * @see packages/server/src/gc.ts
25
+ */
26
+ /**
27
+ * The single constructor for a `gc/pending.json` key:
28
+ * `<collectionPrefix>/gc/pending.json`. `collectionPrefix` is the
29
+ * `<…>/manifests/<collection>` segment — this helper adds the ledger's
30
+ * relative path. Route all callers here so the key shape lives in one
31
+ * place, mirroring {@link logObjectKey} in `log-key.ts` for the sibling
32
+ * `log/<seq>.json` shape.
33
+ */
34
+ const gcPendingKey = (collectionPrefix) => `${collectionPrefix}/gc/pending.json`;
35
+ /**
36
+ * Read + parse `gc/pending.json` at `key`. Returns `null` on
37
+ * not-found.
38
+ *
39
+ * @throws BaerlyError{code:"InvalidResponse"} — body is not valid
40
+ * JSON, or `schema_version` is unknown, or the shape fails
41
+ * the runtime guard.
42
+ */
43
+ const readGcPending = async (storage, key, opts) => {
44
+ const got = await storage.get(key, opts);
45
+ if (got === null) return null;
46
+ let parsed;
47
+ try {
48
+ parsed = decodeJsonBytes(got.body);
49
+ } catch (error) {
50
+ throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: body is not valid JSON`, { cause: error });
51
+ }
52
+ return {
53
+ json: assertGcPending(parsed, key),
54
+ etag: got.etag
55
+ };
56
+ };
57
+ /**
58
+ * Create `gc/pending.json` if-and-only-if it does not exist (S3
59
+ * `If-None-Match: "*"`). Use this once per collection at first GC
60
+ * run; subsequent updates go through {@link casUpdateGcPending}.
61
+ *
62
+ * @throws BaerlyError{code:"WriteConflict"} — the key already exists.
63
+ * @throws BaerlyError{code:"InvalidResponse"} — `initial` fails the
64
+ * runtime shape guard.
65
+ */
66
+ const createGcPending = async (storage, key, initial, opts) => {
67
+ assertGcPending(initial, key);
68
+ const body = encodeJsonBytes(initial);
69
+ const putOpts = {
70
+ ifNoneMatch: "*",
71
+ contentType: GC_PENDING_CONTENT_TYPE,
72
+ ...opts?.signal !== void 0 && { signal: opts.signal }
73
+ };
74
+ let result;
75
+ try {
76
+ result = await storage.put(key, body, putOpts);
77
+ } catch (error) {
78
+ throw translateCasError(error, key);
79
+ }
80
+ return {
81
+ json: initial,
82
+ etag: result.etag
83
+ };
84
+ };
85
+ /**
86
+ * Read-modify-write `gc/pending.json` under CAS, with a bounded retry
87
+ * loop. Each attempt re-reads the latest body, hands the `mutator`
88
+ * that latest value, and writes the result with
89
+ * `If-Match: <latest etag>`. On `WriteConflict` (a concurrent writer landed
90
+ * between this attempt's read and write) the loop re-reads and
91
+ * re-applies the mutator, up to {@link GC_PENDING_CAS_MAX_ATTEMPTS}
92
+ * total attempts, then surfaces `WriteConflict`.
93
+ *
94
+ * `mutator` MUST be a pure, deterministic MERGE of this pass's results
95
+ * INTO the `latest` value it is handed — it is called once per attempt
96
+ * (so it must not have side effects), and it MUST read `latest` rather
97
+ * than ignore it and write a precomputed set. Ignoring `latest` would
98
+ * silently overwrite a concurrent pass's candidates: the
99
+ * If-Match succeeds (it used the fresh etag), so no conflict is
100
+ * raised, and the concurrent marks are lost. See {@link mergeGcPending}.
101
+ *
102
+ * @throws BaerlyError{code:"WriteConflict"} — another writer kept landing a
103
+ * write between this function's read and write for every
104
+ * attempt, OR `key` does not exist. The missing-key case is a
105
+ * CAS precondition failure, not a separate class of fault: the
106
+ * pre-read is an optimisation, and a bare
107
+ * `If-Match: <etag>` PUT against a key another actor deleted
108
+ * would have surfaced `412` → `WriteConflict` from the storage layer
109
+ * anyway. It is deliberately NOT retried — a deleted ledger
110
+ * stays deleted until someone calls {@link createGcPending},
111
+ * which the next `runGc` pass does. `baerly admin restore`
112
+ * deletes `gc/pending.json` on both reseed branches, so a
113
+ * concurrent pass reaches this routinely; `runGc` treats
114
+ * `WriteConflict` as benign best-effort.
115
+ * @throws BaerlyError{code:"InvalidResponse"} — the stored body doesn't
116
+ * parse or fails the shape guard. Kept distinct from the
117
+ * missing-key case on purpose: a caller that tolerates
118
+ * `WriteConflict` as a race must not thereby swallow a corrupt
119
+ * ledger, which fails identically on every future pass.
120
+ */
121
+ const casUpdateGcPending = async (storage, key, mutator, opts) => {
122
+ let lastConflict;
123
+ for (let attempt = 0; attempt < 3; attempt++) {
124
+ const existing = await readGcPending(storage, key, opts);
125
+ if (existing === null) throw new BaerlyError("WriteConflict", `gc/pending.json at ${key} does not exist; it was deleted concurrently, or was never created — see createGcPending`);
126
+ const next = mutator(structuredClone(existing.json));
127
+ assertGcPending(next, key);
128
+ const body = encodeJsonBytes(next);
129
+ const putOpts = {
130
+ ifMatch: existing.etag,
131
+ contentType: GC_PENDING_CONTENT_TYPE,
132
+ ...opts?.signal !== void 0 && { signal: opts.signal }
133
+ };
134
+ try {
135
+ return {
136
+ json: next,
137
+ etag: (await storage.put(key, body, putOpts)).etag
138
+ };
139
+ } catch (error) {
140
+ const translated = translateCasError(error, key);
141
+ if (!isWriteConflict(translated)) throw translated;
142
+ lastConflict = translated;
143
+ }
144
+ }
145
+ throw lastConflict;
146
+ };
147
+ /**
148
+ * Pure merge of one GC pass's results INTO the `latest`
149
+ * `gc/pending.json` value, used as the {@link casUpdateGcPending}
150
+ * mutator. Deterministic, no I/O — the kernel unit + mutation test
151
+ * surface. Splitting it out is what makes the CAS write correct under
152
+ * concurrency: each retry re-merges against fresh `latest` rather than
153
+ * overwriting it with a stale precomputed set.
154
+ *
155
+ * Semantics:
156
+ * - **candidates**: start from `latest.candidates`, DROP any whose key
157
+ * this pass already RESOLVED (`sweptKeys` carries both object DELETEs
158
+ * and ledger-only drops/evictions), then APPEND every fresh mark whose
159
+ * key is not already present AND was not itself resolved this pass. A
160
+ * `graceMillis: 0` pass can mark-and-sweep a key in one go; re-adding a
161
+ * terminal key would be wrong. Dedup also drops a key a concurrent pass
162
+ * already marked. Capped at `maxCandidates`.
163
+ * - **last_swept_at**: the lexicographically LATER of `latest`'s and
164
+ * this pass's (ISO-8601 UTC; `""` sorts lowest so a real timestamp
165
+ * always wins). Never regress a concurrent pass's newer sweep time.
166
+ */
167
+ const mergeGcPending = (latest, pass) => {
168
+ const surviving = latest.candidates.filter((c) => !pass.sweptKeys.has(c.key));
169
+ const present = new Set(surviving.map((c) => c.key));
170
+ const appended = [];
171
+ for (const c of pass.newCandidates) if (!pass.sweptKeys.has(c.key) && !present.has(c.key)) {
172
+ present.add(c.key);
173
+ appended.push(c);
174
+ }
175
+ return {
176
+ schema_version: 1,
177
+ candidates: [...surviving, ...appended].slice(0, pass.maxCandidates),
178
+ last_swept_at: pass.lastSweptAt > latest.last_swept_at ? pass.lastSweptAt : latest.last_swept_at
179
+ };
180
+ };
181
+ /**
182
+ * Accepted `reason` values. Only `"orphan-snapshot"` is still emitted; the
183
+ * other two are legacy-ledger inputs with different sweep fates — see
184
+ * {@link GcCandidate.reason}.
185
+ */
186
+ const VALID_REASONS = /* @__PURE__ */ new Set([
187
+ "stale-log",
188
+ "orphan-snapshot",
189
+ "orphan-content"
190
+ ]);
191
+ /**
192
+ * Runtime guard for `parsed` to be a {@link GcPending}. Throws
193
+ * `BaerlyError{code:"InvalidResponse"}` rather than coercing.
194
+ */
195
+ const assertGcPending = (parsed, key) => {
196
+ if (parsed === null || typeof parsed !== "object") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: parsed body is not an object`);
197
+ const r = parsed;
198
+ if (r["schema_version"] !== 1) throw new BaerlyError("InvalidResponse", unsupportedSchemaVersionMessage(`gc/pending.json at ${key}`, r["schema_version"], 1));
199
+ if (!Array.isArray(r["candidates"])) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates must be an array`);
200
+ for (let i = 0; i < r["candidates"].length; i++) {
201
+ const c = r["candidates"][i];
202
+ if (c === null || typeof c !== "object") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}] is not an object`);
203
+ const cr = c;
204
+ if (typeof cr["key"] !== "string" || cr["key"].length === 0) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].key must be a non-empty string`);
205
+ if (typeof cr["due_at"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].due_at must be a string`);
206
+ if (typeof cr["reason"] !== "string" || !VALID_REASONS.has(cr["reason"])) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].reason must be one of stale-log|orphan-snapshot|orphan-content`);
207
+ if (cr["generation"] !== void 0 && typeof cr["generation"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].generation must be a string when present`);
208
+ }
209
+ if (typeof r["last_swept_at"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: last_swept_at must be a string`);
210
+ if (r["log_scan_cursor"] !== void 0 && typeof r["log_scan_cursor"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: log_scan_cursor must be a string when present`);
211
+ return parsed;
212
+ };
213
+ /**
214
+ * Wrap a storage-level error with `gc/pending.json at <key>`
215
+ * location context. `WriteConflict` (the storage layer's CAS-lost signal)
216
+ * is re-thrown with an annotated message; other `BaerlyError`s pass
217
+ * through; non-`BaerlyError` falls through as `InvalidResponse`.
218
+ */
219
+ const translateCasError = (e, key) => {
220
+ if (isWriteConflict(e)) return new BaerlyError("WriteConflict", `gc/pending.json CAS lost at ${key}: ${e.message}`, { cause: e });
221
+ if (e instanceof BaerlyError) return e;
222
+ return new BaerlyError("InvalidResponse", `gc/pending.json write at ${key} failed: ${String(e)}`, { cause: e });
223
+ };
224
+ /**
225
+ * The single constructor for a log-object key:
226
+ * `<manifestPrefix>/log/<seq>.json`. `manifestPrefix` is the
227
+ * `<…>/manifests/<collection>` segment — this helper adds `/log/`.
228
+ * `<seq>` is unpadded decimal, so lexicographic LIST order is not numeric
229
+ * order (`log/10.json` precedes `log/2.json`). The descending base-32 LSN
230
+ * encoding applies to LSN values and the LSN half of `/v1/since` cursors,
231
+ * not these keys.
232
+ * Route all callers here so the key shape lives in one place.
233
+ */
234
+ const logObjectKey = (manifestPrefix, seq) => `${manifestPrefix}/log/${seq}.json`;
235
+ // packages/protocol/src/snapshot-hash.ts
236
+ /**
237
+ * SHA-256 of `bytes` as a 64-char lowercase hex string. Used to seal
238
+ * snapshot filenames so a crashed mid-PUT can't produce a body that
239
+ * readers consume as truth: the filename embeds the hash; readers
240
+ * recompute on load and reject any mismatch as "file missing."
241
+ *
242
+ * Distinct from {@link versionFromContent} (the legacy 32-hex content-key
243
+ * scheme) — snapshot bodies are larger and longer-lived;
244
+ * 256-bit collision resistance matters here.
245
+ */
246
+ const snapshotHash = (bytes) => sha256Hex(bytes);
247
+ // packages/server/src/caller-facing-error.ts
248
+ /**
249
+ * Errors whose message is written for the caller of the public API rather
250
+ * than for the operator. The HTTP layer exposes a contextual code's message
251
+ * (`InvalidConfig`) only for errors in this set; any other `InvalidConfig`,
252
+ * such as a storage or adapter configuration fault that can carry bucket
253
+ * layout, stays scrubbed.
254
+ */
255
+ const CALLER_FACING_ERRORS = /* @__PURE__ */ new WeakSet();
256
+ /** Mark `err` as caller input at the point it is thrown, and return it. */
257
+ const markCallerFacing = (err) => {
258
+ CALLER_FACING_ERRORS.add(err);
259
+ return err;
260
+ };
261
+ /** True when `err` was marked with {@link markCallerFacing}. */
262
+ const isCallerFacing = (err) => CALLER_FACING_ERRORS.has(err);
263
+ /**
264
+ * Run a caller-input check, marking any `BaerlyError` it throws with
265
+ * {@link markCallerFacing}. For shared checks (from `@baerly/protocol`)
266
+ * that cannot mark their own errors.
267
+ */
268
+ const callerFacingCheck = (check) => {
269
+ try {
270
+ check();
271
+ } catch (error) {
272
+ if (error instanceof BaerlyError) markCallerFacing(error);
273
+ throw error;
274
+ }
275
+ };
276
+ // packages/server/src/collection-alias.ts
277
+ const ALIASED_COLLECTION_RESOLUTION = "An earlier release stored this collection under a non-NFC name, and this name addresses the same stored objects, so it cannot be read or written safely. Keep the app on a different NFC name: export the stored data with `baerly admin dump --collection=<stored name>` and restore it with `baerly admin restore` under an NFC name that is not canonically equivalent to either spelling. For a mixed legacy log, dump with --recover-legacy-names selects one exact spelling and requires a matching snapshot or no snapshot.";
278
+ /**
279
+ * `true` when a stored log entry, snapshot, or snapshot manifest that
280
+ * names collection `stored` belongs to collection `expected`. Live
281
+ * folds, compaction, capacity checks, and ordinary exports filter through
282
+ * this guard. Explicit CLI recovery selects exact spellings instead.
283
+ *
284
+ * R2 stores canonically-equivalent keys as one object, so an NFC name
285
+ * addresses the objects a legacy non-NFC name wrote (and vice versa).
286
+ * Those records carry the other spelling. Skipping them would read as an
287
+ * empty collection and let a fold advance the floor past them, after
288
+ * which log retirement deletes them, so a canonically-equivalent but
289
+ * byte-different name throws instead of returning `false`.
290
+ *
291
+ * @throws BaerlyError code="InvalidConfig" — `stored` and `expected`
292
+ * differ but are canonically equivalent. Marked caller-facing.
293
+ */
294
+ const isOwnCollection = (stored, expected) => {
295
+ if (stored === expected) return true;
296
+ if (typeof stored === "string" && stored.normalize("NFC") === expected.normalize("NFC")) throw markCallerFacing(new BaerlyError("InvalidConfig", `collection ${JSON.stringify(expected)} addresses data stored under the canonically-equivalent name ${JSON.stringify(stored)} (a different Unicode normalization); refusing to read or rewrite it`, { resolution: ALIASED_COLLECTION_RESOLUTION }));
297
+ return false;
298
+ };
299
+ // packages/server/src/snapshot.ts
300
+ /**
301
+ * Snapshot file shape + parse. Lifted out of `./compactor.ts` so that
302
+ * `_internal/kernel.ts` — which re-exports these four symbols to the CLI,
303
+ * bench, and tests — does not transitively pull `withObservability` via
304
+ * `compact()`. `./compactor.ts` imports its own snapshot primitives back
305
+ * from this module.
306
+ *
307
+ * @see ../../../docs/spec/sync-protocol.md
308
+ */
309
+ /**
310
+ * Single-level snapshot at L9; the level prefix is forward-compatible
311
+ * with future L0..L9 rolling merges without a wire change.
312
+ */
313
+ const SNAPSHOT_LEVEL = 9;
314
+ /**
315
+ * `minSeq` and `maxSeq` are padded to {@link SEQ_DIGITS} digits so
316
+ * `list(prefix)` returns snapshots in seq order without needing to
317
+ * parse the filename. 12 digits caps at ~10^12 entries per collection;
318
+ * a real bucket hits S3's per-prefix QPS ceiling long before that.
319
+ */
320
+ const SEQ_DIGITS = 12;
321
+ const MAX_SEQ = 10 ** SEQ_DIGITS - 1;
322
+ const pad = (n) => n.toString().padStart(SEQ_DIGITS, "0");
323
+ /**
324
+ * Build the on-bucket key for a snapshot file. `sha256` must be the
325
+ * lowercase hex digest of the canonical body
326
+ * ({@link encodeSnapshotBody}); the filename embeds it so a crashed
327
+ * mid-PUT body that doesn't match its own filename hash is rejected
328
+ * by readers as "missing."
329
+ *
330
+ * @throws BaerlyError code="InvalidConfig" — `minSeq`/`maxSeq` are
331
+ * out of range or `sha256` is not 64 hex chars.
332
+ */
333
+ const snapshotKey = (collectionPrefix, minSeq, maxSeq, sha256) => {
334
+ if (!Number.isInteger(minSeq) || !Number.isInteger(maxSeq) || minSeq < 0 || maxSeq < 0 || minSeq > maxSeq || maxSeq > MAX_SEQ) throw new BaerlyError("InvalidConfig", `snapshotKey: invalid range [${minSeq}, ${maxSeq})`);
335
+ if (!/^[0-9a-f]{64}$/.test(sha256)) throw new BaerlyError("InvalidConfig", "snapshotKey: sha256 must be 64 hex chars");
336
+ return `${collectionPrefix}/snapshot/L${SNAPSHOT_LEVEL}/${pad(minSeq)}-${pad(maxSeq)}-${sha256}.json`;
337
+ };
338
+ /**
339
+ * Canonical byte encoding of a {@link SnapshotBody}. Only the
340
+ * compactor produces snapshots, and only this function does the
341
+ * serialisation — so the byte output is deterministic for a given
342
+ * `SnapshotBody` (identical input ⇒ identical bytes ⇒ identical
343
+ * filename hash).
344
+ */
345
+ const encodeSnapshotBody = (s) => encodeJsonBytes(s);
346
+ /**
347
+ * Load a snapshot file as a `Map<_id, DocumentData>`. Verifies the
348
+ * body hash against the filename, checks the schema version, and
349
+ * cross-checks `body.collection` against the caller's expectation.
350
+ *
351
+ * @example
352
+ * ```ts
353
+ * import { loadSnapshotAsMap } from "@baerly/server/_internal/kernel";
354
+ *
355
+ * const map =
356
+ * srcCurrent.snapshot === null
357
+ * ? new Map<string, DocumentData>()
358
+ * : await loadSnapshotAsMap(src.storage, srcCurrent.snapshot, "tickets");
359
+ * ```
360
+ *
361
+ * @throws BaerlyError code="Internal" — pointer resolves to no body,
362
+ * or the body's SHA-256 doesn't match the hash embedded in the
363
+ * filename. (Protocol invariant violation; a corrupted snapshot
364
+ * the reader cannot continue past.)
365
+ * @throws BaerlyError code="InvalidResponse" — body isn't valid JSON,
366
+ * isn't an object, has an unsupported `schema_version`, or carries a
367
+ * `collection` that doesn't match `expectedCollection`.
368
+ */
369
+ const loadSnapshotAsMap = async (storage, key, expectedCollection, signal) => {
370
+ const got = await storage.get(key, signal !== void 0 ? { signal } : void 0);
371
+ if (got === null) throw new BaerlyError("Internal", `compact: snapshot pointer ${key} resolves to no body; protocol violation`);
372
+ const filename = key.slice(key.lastIndexOf("/") + 1).replace(/\.json$/, "");
373
+ const lastDash = filename.lastIndexOf("-");
374
+ const expectedHash = filename.slice(lastDash + 1);
375
+ const actualHash = await snapshotHash(got.body);
376
+ if (actualHash !== expectedHash) throw new BaerlyError("Internal", `compact: snapshot ${key} body hash mismatch (got ${actualHash}); protocol violation`);
377
+ let parsed;
378
+ try {
379
+ parsed = decodeJsonBytes(got.body);
380
+ } catch (error) {
381
+ throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} body is not valid JSON`, { cause: error });
382
+ }
383
+ if (parsed === null || typeof parsed !== "object") throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} body is not an object`);
384
+ const body = parsed;
385
+ if (body.schema_version !== 1) throw new BaerlyError("InvalidResponse", unsupportedSchemaVersionMessage(`compact: snapshot ${key}`, body.schema_version, 1));
386
+ if (!isOwnCollection(body.collection, expectedCollection)) throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} carries collection ${body.collection}, expected ${expectedCollection}`);
387
+ if (!Array.isArray(body.docs)) throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} body.docs is not an array`);
388
+ const out = /* @__PURE__ */ new Map();
389
+ for (const row of body.docs) out.set(row._id, row.body);
390
+ return out;
391
+ };
392
+ // packages/server/src/option-guards.ts
393
+ /**
394
+ * Shared pre-I/O validation for the internal maintenance option seams
395
+ * (`InternalCompactOptions`, `InternalRunGcOptions`).
396
+ *
397
+ * Those seams are unvalidated by construction — reached by JS callers,
398
+ * in-repo casts, and the `_internal/testing` subpath — yet their values
399
+ * feed seq arithmetic and range bounds. A non-finite value must fail
400
+ * before the first storage operation, so a rejected run costs nothing
401
+ * durable. `compactor.ts` explains the specific NaN corruption at stake.
402
+ *
403
+ * Zero-import leaf beyond `BaerlyError`: both maintenance entry points
404
+ * already carry that import, so consolidating here removes duplication
405
+ * without widening either closure.
406
+ */
407
+ /**
408
+ * Throw `InvalidConfig` unless `value` is an integer at or above `min`.
409
+ * `min` is `0` for a seq-shaped or count-shaped option (zero is a
410
+ * meaningful "do nothing" bound) and `1` for one that must make at least
411
+ * one unit of progress to be well-defined.
412
+ *
413
+ * Callers own the `undefined ⇒ default` decision before calling; this
414
+ * guard rejects rather than defaults, so passing an absent option is a
415
+ * caller bug, not a silently-tolerated input.
416
+ */
417
+ const requireIntegerOption = (fnName, collectionName, optionName, value, min) => {
418
+ if (!Number.isInteger(value) || value < min) throw new BaerlyError("InvalidConfig", `${fnName}(${collectionName}): ${optionName} must be a ${min === 0 ? "non-negative" : "positive"} integer, got ${String(value)}`);
419
+ };
420
+ // packages/server/src/log-walk.ts
421
+ /**
422
+ * Shared log-walk primitives consumed by the read path (`query.ts`),
423
+ * the compactor (`compactor.ts`), and the optional integrity walk in
424
+ * `Writer.#singleAttemptCommit` (`writer.ts`).
425
+ *
426
+ * Two operations: read one log entry, or walk a contiguous range of
427
+ * log entries with bounded parallelism. Each kernel call site
428
+ * previously inlined the same range-build + unbounded `Promise.all`
429
+ * pattern; on a free-tier collection where the compactor lags the
430
+ * tail to 50-100 entries, that fans out 50-100 concurrent GETs per
431
+ * call — and a contended writer multiplies that by its forward
432
+ * probes. `walkLogRange` caps concurrency at
433
+ * {@link MAX_PARALLEL_LOG_READS} so a single call costs at most that
434
+ * many simultaneous GETs against the storage backend.
435
+ *
436
+ * Order invariant: results are returned in seq order regardless of
437
+ * resolution order. The read-side fold is order-sensitive (`U` then
438
+ * `D` on the same doc must apply in that order); callers may iterate
439
+ * the returned array as-is.
440
+ *
441
+ * Signal invariant: when the caller's `AbortSignal` fires, no further
442
+ * chunks dispatch. In-flight reads see the signal via the underlying
443
+ * `Storage.get` call.
444
+ */
445
+ /**
446
+ * Like {@link readLogEntry}, but also surfaces `bytes` — the
447
+ * byteLength of the STORED log-object body exactly as it was GET back
448
+ * from storage (`got.body.byteLength`).
449
+ *
450
+ * The compactor uses this to sum the byte cost of the folded slice.
451
+ * The stored body byteLength IS what the writer PUT for each entry,
452
+ * so summing `got.body.byteLength` over the folded range yields the
453
+ * exact cost — no re-encode, no round-trip assumption (a re-encode
454
+ * of the parsed `LogEntry` could drift if key-order/whitespace ever
455
+ * diverged from what was PUT).
456
+ *
457
+ * Same error semantics as {@link readLogEntry}.
458
+ */
459
+ const readLogEntryWithBytes = async (storage, key, opts) => {
460
+ const got = await storage.get(key, opts?.signal !== void 0 ? { signal: opts.signal } : void 0);
461
+ if (got === null) throw new BaerlyError("Internal", `log-walk: missing log entry at ${key}; protocol invariant violation`);
462
+ opts?.onBody?.(got.body.byteLength);
463
+ let entry;
464
+ try {
465
+ entry = decodeJsonBytes(got.body);
466
+ } catch (error) {
467
+ throw new BaerlyError("InvalidResponse", `log-walk: malformed log entry at ${key}`, { cause: error });
468
+ }
469
+ if (typeof entry !== "object" || entry === null || Array.isArray(entry)) throw new BaerlyError("InvalidResponse", `log-walk: log entry at ${key} is not a JSON object`);
470
+ return {
471
+ entry,
472
+ bytes: got.body.byteLength
473
+ };
474
+ };
475
+ /**
476
+ * Walk `[fromSeq, toSeqExclusive)` of `${logPrefix}/log/<seq>.json`
477
+ * in chunks of {@link MAX_PARALLEL_LOG_READS} concurrent GETs.
478
+ * Returns the materialised entries in seq order.
479
+ *
480
+ * Retention precondition: derive `fromSeq` from a fresh `current.json`
481
+ * read and require `fromSeq >= current.log_seq_start`. The floor and
482
+ * starting sequence must come from that same manifest read. Entries below
483
+ * the floor may already be reclaimed; a sub-floor walk that reaches one of
484
+ * those holes throws `Internal` even when later live entries still exist.
485
+ * This storage-level helper intentionally accepts no manifest and cannot
486
+ * enforce the precondition for its caller.
487
+ *
488
+ * Empty range (`fromSeq >= toSeqExclusive`) returns `[]` and issues
489
+ * zero GETs.
490
+ *
491
+ * Same error semantics as {@link readLogEntry}: a missing entry
492
+ * throws `Internal`, a malformed body throws `InvalidResponse`.
493
+ */
494
+ const walkLogRange = async (storage, logPrefix, fromSeq, toSeqExclusive, opts) => {
495
+ return (await walkLogRangeWithBytes(storage, logPrefix, fromSeq, toSeqExclusive, opts)).map((r) => r.entry);
496
+ };
497
+ /**
498
+ * Like {@link walkLogRange}, but each element also carries `bytes` —
499
+ * the STORED log-object body byteLength (see {@link readLogEntryWithBytes}).
500
+ * Same seq-order, empty-range, error, and bounded-parallelism
501
+ * ({@link MAX_PARALLEL_LOG_READS}) guarantees as {@link walkLogRange};
502
+ * this is the bytes-aware core `walkLogRange` is implemented on top of.
503
+ *
504
+ * The compactor consumes this so it gets BOTH the parsed entries (for
505
+ * the fold) AND the exact byte sum (for `mean_entry_bytes` stamping) from a
506
+ * single walk.
507
+ */
508
+ const walkLogRangeWithBytes = async (storage, logPrefix, fromSeq, toSeqExclusive, opts) => {
509
+ if (fromSeq >= toSeqExclusive) return [];
510
+ const total = toSeqExclusive - fromSeq;
511
+ const out = Array.from({ length: total });
512
+ for (let chunkStart = 0; chunkStart < total; chunkStart += 16) {
513
+ opts?.signal?.throwIfAborted();
514
+ const chunkEnd = Math.min(chunkStart + 16, total);
515
+ const promises = [];
516
+ for (let i = chunkStart; i < chunkEnd; i++) {
517
+ const seq = fromSeq + i;
518
+ promises.push(readLogEntryWithBytes(storage, logObjectKey(logPrefix, seq), opts));
519
+ }
520
+ const results = await Promise.all(promises);
521
+ for (let i = 0; i < results.length; i++) out[chunkStart + i] = results[i];
522
+ }
523
+ return out;
524
+ };
525
+ /**
526
+ * Fold a sequence of `LogEntry` records onto a doc-id-keyed map,
527
+ * applying the protocol's per-doc-replace semantics:
528
+ *
529
+ * - `I` / `U`: when `entry.after !== undefined`, set
530
+ * `map.set(entry.doc_id, entry.after)`. Entries with `after ===
531
+ * undefined` (the partial-merge writer's future patch-only shape)
532
+ * are ignored — today's writer always emits `after`, so this is a
533
+ * forward-compat guard, not a live branch.
534
+ * - `D`: tombstone — `map.delete(entry.doc_id)`.
535
+ *
536
+ * Entries whose `collection` does not match `opts.collection`, or
537
+ * whose `doc_id` is `undefined`, are skipped.
538
+ *
539
+ * This is the canonical fold used by the read path (`query.ts`).
540
+ * Centralising it keeps the
541
+ * "straight `set` on I/U; tombstone on D" protocol invariant in one place.
542
+ *
543
+ * @see ../../../docs/spec/sync-protocol.md
544
+ */
545
+ const foldLogEntriesOnto = (map, entries, opts) => {
546
+ const { collection } = opts;
547
+ for (const entry of entries) {
548
+ if (!isOwnCollection(entry.collection, collection)) continue;
549
+ if (entry.doc_id === void 0) continue;
550
+ switch (entry.op) {
551
+ case "I":
552
+ case "U":
553
+ if (entry.after === void 0) continue;
554
+ map.set(entry.doc_id, entry.after);
555
+ break;
556
+ case "D": map.delete(entry.doc_id);
557
+ }
558
+ }
559
+ };
560
+ // packages/server/src/log-tail.ts
561
+ /**
562
+ * Tolerant forward-probe for the true committed log tail. The strict
563
+ * `[log_seq_start, hint)` range is dense (a hole is corruption, owned
564
+ * by `walkLogRange`); this owns only the tolerant `[hint, ∞)` probe,
565
+ * where `hint` is a lower bound — the real tail may sit at or past it.
566
+ */
567
+ /**
568
+ * The forward-probe cap for a read in the active invocation:
569
+ * `min(LOG_FORWARD_PROBE_CAP, ledger remaining on pool)`. Every read path
570
+ * that probes past `tail_hint` (collection reads, `/v1/since`) sizes its
571
+ * probe here, so a probe never plans more GETs than the request can
572
+ * issue, and running out is a capacity refusal rather than the runaway
573
+ * alarm. Without a ledger (or with one that never refuses, as on Node) the
574
+ * runaway cap applies.
575
+ */
576
+ const forwardProbeCap = (pool = "internal") => {
577
+ const remaining = currentRequestLedger()?.remaining(pool) ?? 1e400;
578
+ return remaining < 1e5 ? {
579
+ slots: Math.max(0, remaining),
580
+ bound: "request"
581
+ } : {
582
+ slots: LOG_FORWARD_PROBE_CAP,
583
+ bound: "runaway"
584
+ };
585
+ };
586
+ /**
587
+ * A storage call refused before it was sent: the request ledger's
588
+ * `CapacityExceeded`, or a platform subrequest-limit refusal (both carry
589
+ * `cause.refused`). Nothing was read or changed by the refused call.
590
+ */
591
+ const isStorageRefusal = (error) => error instanceof BaerlyError && error.cause?.refused === true;
592
+ /**
593
+ * Probe a bounded chunk of committed entries from `hint`. An occupied
594
+ * chunk certifies only that the tail is at or past its exclusive bound.
595
+ * Decode failures throw by default. With tolerant occupancy probing,
596
+ * malformed slots remain occupied, `complete` becomes false, and probing
597
+ * continues to the first missing slot or cap.
598
+ *
599
+ * With `stopOnRefusal`, a slot GET refused before it was sent (see
600
+ * {@link isStorageRefusal}) ends the chunk instead of throwing: an
601
+ * "at least" chunk whose `lowerBound` is the refused slot, carrying the
602
+ * entries read before it, so a caller delivering prefixes keeps them.
603
+ */
604
+ const probeTailChunk = async (storage, logPrefix, hint, opts) => {
605
+ const cap = opts?.cap ?? 1e5;
606
+ const getOpts = opts?.signal !== void 0 ? { signal: opts.signal } : void 0;
607
+ const entries = [];
608
+ let complete = true;
609
+ for (let i = 0; i < cap; i++) {
610
+ const seq = hint + i;
611
+ const key = logObjectKey(logPrefix, seq);
612
+ let got;
613
+ try {
614
+ got = await storage.get(key, getOpts);
615
+ } catch (error) {
616
+ if (opts?.stopOnRefusal === true && isStorageRefusal(error)) return {
617
+ kind: "at-least",
618
+ lowerBound: seq,
619
+ entries,
620
+ complete
621
+ };
622
+ throw error;
623
+ }
624
+ if (got === null) return {
625
+ kind: "exact",
626
+ tail: seq,
627
+ entries,
628
+ complete
629
+ };
630
+ opts?.onBody?.(got.body.byteLength);
631
+ try {
632
+ entries.push(decodeJsonBytes(got.body));
633
+ } catch (error) {
634
+ if (opts?.tolerateMalformed === true) {
635
+ complete = false;
636
+ continue;
637
+ }
638
+ throw new BaerlyError("InvalidResponse", `probeTailChunk: malformed log entry at ${key}: ${error.message}`, { cause: error });
639
+ }
640
+ }
641
+ return {
642
+ kind: "at-least",
643
+ lowerBound: hint + cap,
644
+ entries,
645
+ complete
646
+ };
647
+ };
648
+ /**
649
+ * Discover the true committed tail and fold entries in `[hint, tail)`.
650
+ * `tail` is the first empty seq (>= hint); `entries` are the
651
+ * LogEntries in `[hint, tail)` in seq order.
652
+ *
653
+ * Retention precondition: derive `hint` from a fresh `current.json` read
654
+ * and require `hint >= current.log_seq_start`; the usual start is
655
+ * `Math.max(current.log_seq_start, current.tail_hint)`. The floor and hint
656
+ * must come from that same manifest read. Entries below the floor may
657
+ * already be reclaimed, and this probe interprets the first missing slot
658
+ * as the tail. A sub-floor hint may therefore report a false tail and omit
659
+ * later live entries. This storage-level helper intentionally accepts no
660
+ * manifest and cannot enforce the precondition for its caller.
661
+ *
662
+ * `cap` bounds the walk; exhausting it THROWS `Internal` (never silently
663
+ * truncates) — see the cap-exhaustion comment below.
664
+ */
665
+ const probeTailFrom = async (storage, logPrefix, hint, opts) => {
666
+ const result = await probeTailChunk(storage, logPrefix, hint, opts);
667
+ if (result.kind === "exact") return {
668
+ tail: result.tail,
669
+ entries: result.entries
670
+ };
671
+ throw new BaerlyError("Internal", `probeTailFrom: forward probe exceeded ${opts?.cap ?? 1e5} from hint ${hint} on ${logPrefix}`);
672
+ };
673
+ /**
674
+ * {@link probeTailFrom} for a read, capped by {@link forwardProbeCap}. When
675
+ * the request ledger set the cap and every capped slot is occupied, the
676
+ * tail is past what this request can probe: throws `refusal()` (a whole
677
+ * `CapacityExceeded` answer) rather than the runaway alarm. `onBody` sees
678
+ * each stored body length before decode, as on {@link probeTailChunk}.
679
+ *
680
+ * @throws the `refusal()` error when the ledger cap is exhausted.
681
+ * @throws BaerlyError code="Internal" when {@link LOG_FORWARD_PROBE_CAP} is.
682
+ */
683
+ const probeReadTail = async (storage, logPrefix, hint, opts) => {
684
+ const cap = forwardProbeCap(opts.pool);
685
+ const result = await probeTailChunk(storage, logPrefix, hint, {
686
+ cap: cap.slots,
687
+ ...opts.onBody !== void 0 && { onBody: opts.onBody },
688
+ ...opts.signal !== void 0 && { signal: opts.signal }
689
+ });
690
+ if (result.kind === "exact") return {
691
+ tail: result.tail,
692
+ entries: result.entries
693
+ };
694
+ if (cap.bound === "request") throw opts.refusal();
695
+ throw new BaerlyError("Internal", `probeReadTail: forward probe exceeded ${cap.slots} from hint ${hint} on ${logPrefix}`);
696
+ };
697
+ /**
698
+ * First empty log seq at/after `hint` — the slot a new commit creates —
699
+ * found by galloping search (`O(log gap)` GETs vs `probeTailFrom`'s
700
+ * `O(gap)`). Used by the writer's per-commit tail-find, where `tail_hint`
701
+ * can lag the true tail. Position only; no bodies.
702
+ *
703
+ * PRECONDITION: occupancy MUST be a dense prefix from `hint` (galloping
704
+ * assumes monotone occupied→empty; a hole ABOVE `hint` would be skipped
705
+ * and the gallop could return a tail past live entries). Contrast
706
+ * `probeTailFrom`, which stops at the first 404 and is hole-tolerant.
707
+ */
708
+ const findLogTail = async (storage, logPrefix, hint, opts) => {
709
+ const getOpts = opts?.signal !== void 0 ? { signal: opts.signal } : void 0;
710
+ const exists = async (seq) => await storage.get(logObjectKey(logPrefix, seq), getOpts) !== null;
711
+ if (!await exists(hint)) return hint;
712
+ let lo = hint;
713
+ let step = 1;
714
+ let hi = hint + step;
715
+ while (await exists(hi)) {
716
+ lo = hi;
717
+ step *= 2;
718
+ hi = lo + step;
719
+ if (step > 1e5) throw new BaerlyError("Internal", `findLogTail: galloping probe exceeded ${LOG_FORWARD_PROBE_CAP} from hint ${hint} on ${logPrefix}`);
720
+ }
721
+ while (hi - lo > 1) {
722
+ const mid = lo + Math.floor((hi - lo) / 2);
723
+ if (await exists(mid)) lo = mid;
724
+ else hi = mid;
725
+ }
726
+ return hi;
727
+ };
728
+ // packages/server/src/collection-key.ts
729
+ /**
730
+ * Splits a `current.json` key (`<collectionPrefix>/current.json`) into the
731
+ * collection's key prefix and its trailing name segment. `compact()`,
732
+ * `runGc()`, `retireLogRange()` and the maintenance runner all take the
733
+ * key and derive these the same way.
734
+ */
735
+ const collectionFromCurrentJsonKey = (currentJsonKey) => {
736
+ const prefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf("/"));
737
+ return {
738
+ prefix,
739
+ name: prefix.slice(prefix.lastIndexOf("/") + 1)
740
+ };
741
+ };
742
+ // packages/server/src/snapshot-projection.ts
743
+ /**
744
+ * Byte-exact projection of the snapshot a fold rebuilds, entry by entry,
745
+ * as the compactor encodes it. Shared by the growth-refusal check
746
+ * (`./capacity.ts`) and the compactor's bytes cut (`./compactor.ts`), so
747
+ * the two agree on where a fold can stop; a module of its own because the
748
+ * compactor cannot import `./capacity.ts` without a cycle through
749
+ * `./maintenance.ts`.
750
+ */
751
+ /** Encoded size of one snapshot row: the `{ _id, body }` element the compactor writes. */
752
+ const rowBytes = (docId, body) => encodeJsonBytes({
753
+ _id: docId,
754
+ body
755
+ }).byteLength;
756
+ /** Separators between `rows` elements of the snapshot's `docs` array. */
757
+ const separators = (rows) => Math.max(rows - 1, 0);
758
+ /**
759
+ * Encoded size of an empty snapshot body for `collection` whose header
760
+ * records `max_seq`. Rows add their own bytes plus one separator between
761
+ * each pair, inside the `docs` array.
762
+ */
763
+ const headerBytes = (collection, maxSeq) => encodeSnapshotBody({
764
+ schema_version: 1,
765
+ min_seq: 0,
766
+ max_seq: maxSeq,
767
+ collection,
768
+ docs: []
769
+ }).byteLength;
770
+ /**
771
+ * Project the snapshot a fold would build from `head`'s stored figures and
772
+ * its rows (`base`), one entry at a time, byte for byte as the compactor
773
+ * encodes it: each row, one separator between rows, and the header, whose
774
+ * `max_seq` is the fold's end. A stored snapshot's `max_seq` is
775
+ * `log_seq_start` (the compactor writes both from the same fold end); a
776
+ * never-folded collection (`snapshot_bytes === 0`) starts empty at 0.
777
+ *
778
+ * `bytes` keeps the stored header, so a growth check made now does not
779
+ * know the `max_seq` its fold will record; `CAPACITY_BYTES_MARGIN` covers
780
+ * that header growth. `bytesAt` is exact for a fold whose end is known.
781
+ *
782
+ * @internal — exported for `capacity.test.ts`.
783
+ */
784
+ const projectSnapshot = (head, base, collection) => {
785
+ const overlay = /* @__PURE__ */ new Map();
786
+ const sizeOf = (docId) => {
787
+ const known = overlay.get(docId);
788
+ if (known !== void 0) return known ?? void 0;
789
+ const body = base.get(docId);
790
+ return body === void 0 ? void 0 : rowBytes(docId, body);
791
+ };
792
+ const folded = head.snapshot_bytes !== 0;
793
+ let header = headerBytes(collection, folded ? head.log_seq_start : 0);
794
+ let rows = head.snapshot_rows;
795
+ let rowSum = folded ? head.snapshot_bytes - header - separators(rows) : 0;
796
+ const sizeNow = () => header + rowSum + separators(rows);
797
+ let peakRows = rows;
798
+ let peakBytes = sizeNow();
799
+ return {
800
+ get rows() {
801
+ return rows;
802
+ },
803
+ get bytes() {
804
+ return sizeNow();
805
+ },
806
+ get peakRows() {
807
+ return peakRows;
808
+ },
809
+ get peakBytes() {
810
+ return peakBytes;
811
+ },
812
+ bytesAt(maxSeq) {
813
+ return headerBytes(collection, maxSeq) + rowSum + separators(rows);
814
+ },
815
+ addsRow(op, docId, after) {
816
+ return op !== "D" && after !== void 0 && sizeOf(docId) === void 0;
817
+ },
818
+ apply(op, docId, after) {
819
+ if (op !== "D" && after === void 0) return;
820
+ const before = sizeOf(docId);
821
+ if (op === "D" || after === void 0) {
822
+ if (before !== void 0) {
823
+ rows -= 1;
824
+ rowSum -= before;
825
+ }
826
+ overlay.set(docId, null);
827
+ return;
828
+ }
829
+ const next = rowBytes(docId, after);
830
+ if (before === void 0) rows += 1;
831
+ rowSum += next - (before ?? 0);
832
+ overlay.set(docId, next);
833
+ peakRows = Math.max(peakRows, rows);
834
+ peakBytes = Math.max(peakBytes, sizeNow());
835
+ },
836
+ settle(maxSeq) {
837
+ header = headerBytes(collection, maxSeq);
838
+ peakRows = rows;
839
+ peakBytes = sizeNow();
840
+ }
841
+ };
842
+ };
843
+ // packages/server/src/compactor.ts
844
+ /**
845
+ * Compactor: fold a prefix of the live log into a content-
846
+ * hashed snapshot file and CAS-advance `current.json` to swap the
847
+ * pointer.
848
+ *
849
+ * The hard correctness requirement is **atomic snapshot generation**:
850
+ * a compactor that crashes mid-write must not leave a corrupted body
851
+ * that readers consume as truth. The design: every snapshot's filename
852
+ * embeds the SHA-256 of its body. A crashed mid-PUT leaves a body that
853
+ * doesn't match its own filename hash, and readers reject it as
854
+ * "missing." The atomic moment is the CAS-swap of
855
+ * `current.json.snapshot`, which is a single conditional PUT.
856
+ *
857
+ * Order of operations: PUT snapshot body → CAS-advance `current.json`.
858
+ * A crash before the swap leaves an orphan snapshot file; the swap
859
+ * succeeds iff our captured ETag still matches.
860
+ *
861
+ * Why level-prefixed chunked snapshots over the alternatives: a
862
+ * single monolithic snapshot (every compaction rewrites one well-
863
+ * known key) makes partial writes catastrophic and serializes every
864
+ * writer on one key. WAL-checkpointing in the rqlite / Raft tradition
865
+ * requires a consensus layer baerly-storage doesn't have. The Litestream-
866
+ * style multi-level scheme — small fixed number of levels, chunked
867
+ * files keyed by sequence range — keeps random GETs cheap on
868
+ * S3-compatible storage and avoids LIST. Current ship is single-
869
+ * level at L9 (one snapshot replaces the prior; no multi-level merge
870
+ * yet); the key format is forward-compatible with future L0..L9
871
+ * rolling merges without a wire change.
872
+ *
873
+ * @see ../../../docs/spec/sync-protocol.md
874
+ */
875
+ const DEFAULT_MAX_PER_RUN = Number.MAX_SAFE_INTEGER;
876
+ const DEFAULT_MIN_TO_COMPACT = 100;
877
+ const APPLICATION_JSON = "application/json";
878
+ /**
879
+ * Fold a prefix of the live log into a new snapshot and CAS-advance
880
+ * `current.json`. Idempotent: a second run with no new writes is a
881
+ * no-op (below-min-threshold).
882
+ *
883
+ * Single-attempt: on CAS conflict we return
884
+ * `{written: false, skippedReason: "cas-lost"}` — the
885
+ * caller (the cron handler invoking `runScheduledMaintenance` from
886
+ * `./maintenance.ts`) decides whether to schedule another run. The
887
+ * orphan snapshot file just written will be swept by `runGc()`.
888
+ *
889
+ * @throws BaerlyError code="InvalidConfig" — `maxEntriesPerRun` or
890
+ * `knownTail` (the `InternalCompactOptions` seam) is not a
891
+ * non-negative integer, or `maxTailProbeGets` is not a positive
892
+ * integer. Checked before any I/O: a non-finite value would otherwise
893
+ * slip the range guards and write an unreadable `current.json`.
894
+ * @throws BaerlyError code="InvalidResponse" — `current.json` is
895
+ * present but malformed, or a snapshot body fails its schema /
896
+ * collection cross-check.
897
+ * @throws BaerlyError code="Internal" — protocol-invariant violation:
898
+ * a log entry missing inside `[log_seq_start, foldEnd)`, or the
899
+ * prior-snapshot pointer resolves to no body / a body whose hash
900
+ * doesn't match its filename.
901
+ *
902
+ * @example
903
+ * ```ts
904
+ * import { compact } from "@baerly/server/_internal/maintenance";
905
+ *
906
+ * const res = await compact(
907
+ * { storage, currentJsonKey: "app/x/tenant/t/manifests/tickets/current.json" },
908
+ * { minEntriesToCompact: 100 },
909
+ * );
910
+ * if (res.written) console.log("folded", res.entriesFolded, "entries");
911
+ * ```
912
+ */
913
+ const compact = (args, options) => compactInternal(args, options);
914
+ /**
915
+ * {@link compact}, typed to return the {@link InternalCompactResult}
916
+ * snapshot keys. Tests and in-repo tooling reach it via the
917
+ * `@baerly/server/_internal/testing` subpath.
918
+ *
919
+ * @internal
920
+ */
921
+ const compactInternal = async (args, options = {}) => {
922
+ const { storage, currentJsonKey } = args;
923
+ const internal = options;
924
+ const maxPerRun = internal.maxEntriesPerRun ?? DEFAULT_MAX_PER_RUN;
925
+ const maxTailProbeGets = internal.maxTailProbeGets;
926
+ const minToCompact = options.minEntriesToCompact ?? DEFAULT_MIN_TO_COMPACT;
927
+ const ceilingBytes = internal.ceilingBytes ?? Number.POSITIVE_INFINITY;
928
+ const ceilingEntries = internal.ceilingEntries ?? Number.POSITIVE_INFINITY;
929
+ const { prefix: collectionPrefix, name: collectionName } = collectionFromCurrentJsonKey(currentJsonKey);
930
+ const requireSeqOption = (name, value) => requireIntegerOption("compact", collectionName, name, value, 0);
931
+ requireSeqOption("maxEntriesPerRun", maxPerRun);
932
+ requireSeqOption("knownTail", internal.knownTail ?? 0);
933
+ if (maxTailProbeGets !== void 0) requireIntegerOption("compact", collectionName, "maxTailProbeGets", maxTailProbeGets, 1);
934
+ const read = await readCurrentJson(storage, currentJsonKey, options.signal !== void 0 ? { signal: options.signal } : void 0);
935
+ if (read === null) return {
936
+ written: false,
937
+ skippedReason: "current-json-missing",
938
+ previousSnapshotKey: null,
939
+ logSeqStartBefore: 0,
940
+ logSeqStartAfter: 0,
941
+ entriesFolded: 0
942
+ };
943
+ const current = read.json;
944
+ const baseEtag = read.etag;
945
+ const logSeqStartBefore = logSeqStartOf(current);
946
+ const probeFloor = Math.max(logSeqStartBefore, current.tail_hint, internal.knownTail ?? 0);
947
+ let probe;
948
+ if (maxTailProbeGets === void 0) probe = {
949
+ kind: "exact",
950
+ ...await probeTailFrom(storage, collectionPrefix, probeFloor, { ...options.signal !== void 0 && { signal: options.signal } }),
951
+ complete: true
952
+ };
953
+ else {
954
+ const foldReserve = (current.snapshot === null ? 0 : 1) + maxPerRun + 2;
955
+ const requestsLeft = getCurrentContext()?.ledger?.storageRemaining() ?? 1e400;
956
+ probe = await probeTailChunk(storage, collectionPrefix, probeFloor, {
957
+ ...options.signal !== void 0 && { signal: options.signal },
958
+ cap: Math.max(0, Math.min(maxTailProbeGets, requestsLeft - foldReserve))
959
+ });
960
+ }
961
+ const tailIsExact = probe.kind === "exact";
962
+ const discoveredTail = probe.kind === "exact" ? probe.tail : probe.lowerBound;
963
+ const nextSeq = discoveredTail;
964
+ const available = nextSeq - logSeqStartBefore;
965
+ if (available < minToCompact) {
966
+ if (!tailIsExact && discoveredTail <= current.tail_hint) return {
967
+ written: false,
968
+ skippedReason: "probe-budget-checkpointed",
969
+ previousSnapshotKey: current.snapshot,
970
+ logSeqStartBefore,
971
+ logSeqStartAfter: logSeqStartBefore,
972
+ entriesFolded: 0
973
+ };
974
+ if (!tailIsExact) {
975
+ const checkpoint = {
976
+ ...current,
977
+ tail_hint: Math.max(current.tail_hint, discoveredTail)
978
+ };
979
+ assertCurrentJsonTransition(current, checkpoint, currentJsonKey);
980
+ const checkpointBody = encodeJsonBytes(checkpoint);
981
+ const checkpointCasOpts = {
982
+ ifMatch: baseEtag,
983
+ contentType: APPLICATION_JSON,
984
+ ...options.signal !== void 0 && { signal: options.signal }
985
+ };
986
+ try {
987
+ await storage.put(currentJsonKey, checkpointBody, checkpointCasOpts);
988
+ } catch (error) {
989
+ if (isWriteConflict(error)) {
990
+ ctxMetrics().counter("db.compaction.cas_lost_total", 1, { collection: collectionName });
991
+ return {
992
+ written: false,
993
+ skippedReason: "cas-lost",
994
+ previousSnapshotKey: current.snapshot,
995
+ logSeqStartBefore,
996
+ logSeqStartAfter: logSeqStartBefore,
997
+ entriesFolded: 0
998
+ };
999
+ }
1000
+ throw error;
1001
+ }
1002
+ return {
1003
+ written: false,
1004
+ skippedReason: "probe-budget-checkpointed",
1005
+ previousSnapshotKey: current.snapshot,
1006
+ logSeqStartBefore,
1007
+ logSeqStartAfter: logSeqStartBefore,
1008
+ entriesFolded: 0
1009
+ };
1010
+ }
1011
+ if (available > 0) ctxMetrics().counter("db.compaction.below_min_total", 1, { collection: collectionName });
1012
+ return {
1013
+ written: false,
1014
+ skippedReason: "below-min-threshold",
1015
+ previousSnapshotKey: current.snapshot,
1016
+ logSeqStartBefore,
1017
+ logSeqStartAfter: logSeqStartBefore,
1018
+ entriesFolded: 0
1019
+ };
1020
+ }
1021
+ let foldEnd = Math.min(nextSeq, logSeqStartBefore + maxPerRun);
1022
+ const base = current.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(storage, current.snapshot, collectionName, options.signal);
1023
+ const fetched = await walkLogRangeWithBytes(storage, collectionPrefix, logSeqStartBefore, foldEnd, { signal: options.signal });
1024
+ const own = (entry) => isOwnCollection(entry.collection, collectionName) && entry.doc_id !== void 0;
1025
+ let applied = fetched.length;
1026
+ let rowsStopped = false;
1027
+ if (ceilingBytes !== Number.POSITIVE_INFINITY || ceilingEntries !== Number.POSITIVE_INFINITY) {
1028
+ const projection = projectSnapshot({
1029
+ ...current,
1030
+ snapshot_rows: base.size
1031
+ }, base, collectionName);
1032
+ let rowsEnd = 0;
1033
+ let fits = 0;
1034
+ for (const { entry } of fetched) {
1035
+ if (own(entry)) {
1036
+ if (projection.addsRow(entry.op, entry.doc_id, entry.after) && !(projection.rows < ceilingEntries)) {
1037
+ rowsStopped = true;
1038
+ break;
1039
+ }
1040
+ projection.apply(entry.op, entry.doc_id, entry.after);
1041
+ }
1042
+ rowsEnd++;
1043
+ if (projection.bytesAt(logSeqStartBefore + rowsEnd) <= ceilingBytes) fits = rowsEnd;
1044
+ }
1045
+ applied = fits;
1046
+ if (applied === 0 && fetched.length > 0) {
1047
+ const byRows = rowsStopped && rowsEnd === 0;
1048
+ return {
1049
+ written: false,
1050
+ skippedReason: "deferred",
1051
+ deferred: true,
1052
+ deferral: {
1053
+ dimension: byRows ? "rows" : "bytes",
1054
+ snapshotBytes: byRows ? current.snapshot_bytes : projection.bytesAt(logSeqStartBefore + rowsEnd),
1055
+ snapshotRows: byRows ? base.size : projection.rows
1056
+ },
1057
+ previousSnapshotKey: current.snapshot,
1058
+ logSeqStartBefore,
1059
+ logSeqStartAfter: logSeqStartBefore,
1060
+ entriesFolded: 0
1061
+ };
1062
+ }
1063
+ }
1064
+ for (const { entry } of fetched.slice(0, applied)) {
1065
+ if (!own(entry)) continue;
1066
+ switch (entry.op) {
1067
+ case "I":
1068
+ case "U":
1069
+ if (entry.after !== void 0) base.set(entry.doc_id, entry.after);
1070
+ break;
1071
+ case "D": base.delete(entry.doc_id);
1072
+ }
1073
+ }
1074
+ foldEnd = logSeqStartBefore + applied;
1075
+ const foldedSliceBytes = fetched.slice(0, applied).reduce((sum, f) => sum + f.bytes, 0);
1076
+ const sortedDocs = Array.from(base.entries()).toSorted(([a], [b]) => {
1077
+ if (a < b) return -1;
1078
+ if (a > b) return 1;
1079
+ return 0;
1080
+ }).map(([id, body]) => ({
1081
+ _id: id,
1082
+ body
1083
+ }));
1084
+ const bodyBytes = encodeSnapshotBody({
1085
+ schema_version: 1,
1086
+ min_seq: 0,
1087
+ max_seq: foldEnd,
1088
+ collection: collectionName,
1089
+ docs: sortedDocs
1090
+ });
1091
+ const bytesFit = bodyBytes.byteLength <= ceilingBytes;
1092
+ if (!(bytesFit && base.size <= ceilingEntries)) return {
1093
+ written: false,
1094
+ skippedReason: "deferred",
1095
+ deferred: true,
1096
+ deferral: {
1097
+ dimension: bytesFit ? "rows" : "bytes",
1098
+ snapshotBytes: bodyBytes.byteLength,
1099
+ snapshotRows: base.size
1100
+ },
1101
+ previousSnapshotKey: current.snapshot,
1102
+ logSeqStartBefore,
1103
+ logSeqStartAfter: logSeqStartBefore,
1104
+ entriesFolded: 0
1105
+ };
1106
+ const sha256 = await snapshotHash(bodyBytes);
1107
+ const newKey = snapshotKey(collectionPrefix, 0, foldEnd, sha256);
1108
+ const putOpts = {
1109
+ contentType: APPLICATION_JSON,
1110
+ ...options.signal !== void 0 && { signal: options.signal }
1111
+ };
1112
+ await storage.put(newKey, bodyBytes, putOpts);
1113
+ const entriesFolded = foldEnd - logSeqStartBefore;
1114
+ const next = {
1115
+ ...current,
1116
+ snapshot: newKey,
1117
+ log_seq_start: foldEnd,
1118
+ tail_hint: Math.max(current.tail_hint, discoveredTail),
1119
+ snapshot_bytes: bodyBytes.byteLength,
1120
+ snapshot_rows: base.size,
1121
+ mean_entry_bytes: entriesFolded > 0 ? Math.round(foldedSliceBytes / entriesFolded) : current.mean_entry_bytes ?? 0
1122
+ };
1123
+ assertCurrentJsonTransition(current, next, currentJsonKey);
1124
+ const nextBody = encodeJsonBytes(next);
1125
+ const casOpts = {
1126
+ ifMatch: baseEtag,
1127
+ contentType: APPLICATION_JSON,
1128
+ ...options.signal !== void 0 && { signal: options.signal }
1129
+ };
1130
+ try {
1131
+ await storage.put(currentJsonKey, nextBody, casOpts);
1132
+ } catch (error) {
1133
+ if (isWriteConflict(error)) {
1134
+ ctxMetrics().counter("db.compaction.cas_lost_total", 1, { collection: collectionName });
1135
+ return {
1136
+ written: false,
1137
+ skippedReason: "cas-lost",
1138
+ previousSnapshotKey: current.snapshot,
1139
+ newSnapshotKey: newKey,
1140
+ logSeqStartBefore,
1141
+ logSeqStartAfter: logSeqStartBefore,
1142
+ entriesFolded: foldEnd - logSeqStartBefore
1143
+ };
1144
+ }
1145
+ throw error;
1146
+ }
1147
+ const metrics = ctxMetrics();
1148
+ metrics.histogram("db.compact.entries_folded", entriesFolded, { collection: collectionName });
1149
+ if (tailIsExact) metrics.gauge("db.manifest.lag_window_depth", discoveredTail - foldEnd, { collection: collectionName });
1150
+ return {
1151
+ written: true,
1152
+ previousSnapshotKey: current.snapshot,
1153
+ newSnapshotKey: newKey,
1154
+ logSeqStartBefore,
1155
+ logSeqStartAfter: foldEnd,
1156
+ entriesFolded
1157
+ };
1158
+ };
1159
+ // packages/server/src/gc.ts
1160
+ /**
1161
+ * GC mark + sweep.
1162
+ *
1163
+ * `runGc` is a single-pass garbage collector that:
1164
+ * 1. Reads `current.json` (and bootstraps `gc/pending.json` on first
1165
+ * run).
1166
+ * 2. Marks new orphan candidates by LISTing the snapshot prefix and
1167
+ * classifying each key.
1168
+ * 3. Rescues candidates proven live, then sweeps due candidates that
1169
+ * are safe to classify.
1170
+ * 4. CAS-writes the updated `gc/pending.json`.
1171
+ *
1172
+ * Two-phase by design: each mark sits in `gc/pending.json` for a grace
1173
+ * period (default 7 days, see {@link GC_GRACE_PERIOD_MILLIS}) before
1174
+ * sweep may delete it. The grace bounds the worst plausible writer-retry
1175
+ * window — a paused-process writer that resumes hours later still finds
1176
+ * its idempotency anchor on the bucket. Sweep can also resolve a
1177
+ * candidate OUT of the ledger without deleting it, when a generation or
1178
+ * liveness recheck fails.
1179
+ *
1180
+ * **A pass is bounded by the grace it relies on.** Sweep DELETEs go out
1181
+ * in batches of {@link GC_SWEEP_DELETE_BATCH_KEYS}. Before each batch,
1182
+ * a pass whose sweep-gate `current.json` read is older than
1183
+ * {@link GC_PASS_GRACE_FRACTION} of the grace issues no further DELETEs;
1184
+ * the unissued candidates stay pending, still due, for a later pass.
1185
+ * That bounds how stale a DELETE's liveness proof can be (sync-protocol
1186
+ * invariant 14) without a lease or a scheduler.
1187
+ *
1188
+ * Stale log objects are reclaimed by a sequence window rather than a
1189
+ * timed mark-and-sweep. See `log-retention.ts` for the computed-range
1190
+ * deletion path.
1191
+ *
1192
+ * Unbounded by default — the run marks and sweeps the entire eligible
1193
+ * set in one pass. Callers on a per-invocation request limit (Cloudflare
1194
+ * Workers) opt INTO caps via the `CLOUDFLARE_FREE_TIER` /
1195
+ * `CLOUDFLARE_PAID_TIER` profiles' mark and sweep knobs
1196
+ * (`InternalRunGcOptions`, not on the public `RunGcOptions`); the
1197
+ * per-pass worst cases are on `CLOUDFLARE_FREE_TIER`.
1198
+ *
1199
+ * One category of orphan:
1200
+ * - `orphan-snapshot`: a canonical
1201
+ * `<collectionPrefix>/snapshot/L9/...` key not equal to
1202
+ * `current.snapshot`. Each compactor run replaces the pointer; the
1203
+ * prior file becomes unreferenced. Discovery is scoped to this
1204
+ * binary's owned `snapshot/L9/` namespace. Future L0-L8 layouts
1205
+ * stay opaque to this binary and do not consume the bounded mark
1206
+ * window. Opaque L9 keys are ignored during mark and evicted from
1207
+ * legacy ledgers without a DELETE; no current writer emits one.
1208
+ *
1209
+ * **Mark window rule.** Every pass LISTs `snapshot/L9/` from the
1210
+ * lexicographic start — no persisted cursor, so no orphan can sit
1211
+ * behind a position the scan never revisits (a restore that deletes the
1212
+ * ledger, a stale-generation drop, or a lost CAS simply re-marks on the
1213
+ * next pass). The window is `maxMarks` plus every key the pass will
1214
+ * certainly skip: the snapshot keys already in `gc/pending.json` and the
1215
+ * one live `current.snapshot`. The loop stops after `maxMarks` NEW
1216
+ * marks. Without the widening, older keys sort first and a cohort
1217
+ * waiting out its 7-day grace fills a `maxMarks`-key window, capping
1218
+ * marking at `maxMarks` per grace while folds keep orphaning snapshots.
1219
+ * The widening is capped at {@link GC_MARK_LIST_PAGE_KEYS} (one full
1220
+ * provider page) and never shrinks the window below `maxMarks`, so it
1221
+ * adds no LIST page request beyond what `maxMarks` alone costs: one
1222
+ * request per 1000 keys, more only if the provider truncates a page
1223
+ * short. Marking only adds ledger entries; deletion authority stays with
1224
+ * the sweep gate below.
1225
+ *
1226
+ * Progress: within the protocol-written L9 keyspace at most ONE key is
1227
+ * permanently unmarkable (the live `current.snapshot`), so for any
1228
+ * `maxMarks >= 1` a pass whose ledger has room marks an unpending orphan
1229
+ * if one exists in the window. Opaque L9 keys (non-canonical names) are
1230
+ * skipped but still occupy window slots; no current writer emits one.
1231
+ *
1232
+ * Ceiling: `GC_MAX_PENDING_CANDIDATES` (1000) bounds the in-flight
1233
+ * cohort, so a collection reclaims at most ~1000 replaced snapshots per
1234
+ * 7-day grace — about 143 folds/day. At the cap the window holds only
1235
+ * pending keys and `mergeGcPending` drops appends past the cap, so
1236
+ * marking stops until the oldest cohort comes due and is swept; a
1237
+ * collection folding faster than that accumulates the excess.
1238
+ *
1239
+ * **`content/` is deliberately NOT a category.** Legacy
1240
+ * `<collectionPrefix>/content/<sha>.json` side objects — written by
1241
+ * v0.6.0, and still written by a v0.6.0 node during a mixed rollout —
1242
+ * are inert: no current writer creates one, no reader opens one. GC
1243
+ * never LISTs, reads, or deletes under that prefix, so they cost storage
1244
+ * and nothing else, and an operator who wants the bytes back deletes the
1245
+ * prefix directly (`docs/guide/backups.md`). An `orphan-content` entry
1246
+ * found in a legacy ledger is EVICTED, not swept — see the sweep gate's
1247
+ * legacy arm.
1248
+ *
1249
+ * CAS-lost on `gc/pending.json` is non-fatal: the DELETEs already
1250
+ * issued are durable, so we return a successful result and the next
1251
+ * pass will pick up any work this pass lost.
1252
+ *
1253
+ * **Not fault-isolated, by design.** Every storage call in Steps 1-5 —
1254
+ * the `current.json`/`gc/pending.json` reads, the mark-phase `LIST`s,
1255
+ * the sweep DELETEs — is uncaught within `runGc` itself; a throw from
1256
+ * any of them aborts the whole pass. That's a deliberate fail-safe, not
1257
+ * a gap to close with a `try`/`catch` around one call: Steps 3-4 re-LIST
1258
+ * from scratch every pass rather than trusting partial progress, sweep
1259
+ * DELETEs are idempotent, and the pending-ledger CAS in Step 5 hasn't
1260
+ * happened yet when an earlier step throws — so an abort mid-pass loses
1261
+ * no durable state and deletes nothing it shouldn't. This is fuzz-tested
1262
+ * directly: `maintenance-crash-fuzz.test.ts` aborts the K-th storage op
1263
+ * inside `runGc` and asserts the reader still returns every live row.
1264
+ */
1265
+ const DEFAULT_MAX_MARKS = Number.MAX_SAFE_INTEGER;
1266
+ const DEFAULT_MAX_SWEEPS = Number.MAX_SAFE_INTEGER;
1267
+ const zeroGcResult = () => ({
1268
+ marked: { orphan_snapshot: 0 },
1269
+ swept: 0,
1270
+ dropped: {
1271
+ stale_generation: 0,
1272
+ still_live: 0
1273
+ },
1274
+ pendingDepth: 0
1275
+ });
1276
+ /**
1277
+ * Single GC pass — mark new orphans, sweep due-elapsed candidates,
1278
+ * persist via CAS-update on `gc/pending.json`.
1279
+ *
1280
+ * Returns immediately if `current.json` is missing — there's nothing
1281
+ * to do until a writer has bootstrapped the collection.
1282
+ *
1283
+ * @example
1284
+ * ```ts
1285
+ * import { runGc } from "@baerly/server/_internal/maintenance";
1286
+ *
1287
+ * const r = await runGc({ storage, currentJsonKey });
1288
+ * console.log(`marked ${r.marked.orphan_snapshot} orphan snapshots, swept ${r.swept}`);
1289
+ * ```
1290
+ */
1291
+ const runGc = async (args, options = {}) => {
1292
+ const { storage, currentJsonKey } = args;
1293
+ const internal = options;
1294
+ const grace = internal.graceMillis ?? 6048e5;
1295
+ const maxMarks = internal.maxMarksPerRun ?? DEFAULT_MAX_MARKS;
1296
+ const maxSweeps = internal.maxSweepsPerRun ?? DEFAULT_MAX_SWEEPS;
1297
+ const now = internal.now ?? (() => /* @__PURE__ */ new Date());
1298
+ const monotonicNow = internal.monotonicNow ?? (() => performance.now());
1299
+ /** Both clocks at one instant; see {@link elapsedSince}. */
1300
+ const stamp = () => ({
1301
+ wall: now().getTime(),
1302
+ mono: monotonicNow()
1303
+ });
1304
+ /** The larger of the two clocks' elapsed times, so neither can understate it. */
1305
+ const elapsedSince = (from) => Math.max(now().getTime() - from.wall, monotonicNow() - from.mono);
1306
+ const { prefix: collectionPrefix, name: collectionName } = collectionFromCurrentJsonKey(currentJsonKey);
1307
+ const pendingKey = gcPendingKey(collectionPrefix);
1308
+ const signal = options.signal;
1309
+ const signalOpts = signal !== void 0 ? { signal } : void 0;
1310
+ const currentReadAt = stamp();
1311
+ const cur = await readCurrentJson(storage, currentJsonKey, signalOpts);
1312
+ if (cur === null) return zeroGcResult();
1313
+ const current = cur.json;
1314
+ let pending = await readGcPending(storage, pendingKey, signalOpts);
1315
+ if (pending === null) {
1316
+ const initial = {
1317
+ schema_version: 1,
1318
+ candidates: [],
1319
+ last_swept_at: ""
1320
+ };
1321
+ try {
1322
+ pending = await createGcPending(storage, pendingKey, initial, signalOpts);
1323
+ } catch (error) {
1324
+ if (isWriteConflict(error)) {
1325
+ pending = await readGcPending(storage, pendingKey, signalOpts);
1326
+ if (pending === null) throw error;
1327
+ } else throw error;
1328
+ }
1329
+ }
1330
+ const known = new Set(pending.json.candidates.map((c) => c.key));
1331
+ const markGeneration = current.generation !== void 0 ? { generation: current.generation } : {};
1332
+ const newCandidates = [];
1333
+ let markedOrphanSnapshot = 0;
1334
+ const snapshotPrefix = `${collectionPrefix}/snapshot/L9/`;
1335
+ const pendingSnapshotKeys = pending.json.candidates.filter((c) => c.key.startsWith(snapshotPrefix)).length;
1336
+ for await (const entry of storage.list(snapshotPrefix, listWindow(markWindowKeys(maxMarks, pendingSnapshotKeys), void 0, signal))) {
1337
+ if (markedOrphanSnapshot >= maxMarks) break;
1338
+ if (entry.key === current.snapshot) continue;
1339
+ if (parseMaxSeqFromCanonicalSnapshotKey(entry.key, collectionPrefix) === null) continue;
1340
+ if (known.has(entry.key)) continue;
1341
+ newCandidates.push({
1342
+ key: entry.key,
1343
+ due_at: computeDueAt(now, grace),
1344
+ reason: "orphan-snapshot",
1345
+ ...markGeneration
1346
+ });
1347
+ markedOrphanSnapshot++;
1348
+ }
1349
+ const nowMs = now().getTime();
1350
+ const sweepCandidates = [...pending.json.candidates, ...newCandidates];
1351
+ const hasDueSnapshot = sweepCandidates.some((candidate) => candidate.reason === "orphan-snapshot" && Date.parse(candidate.due_at) <= nowMs);
1352
+ const freshReadAt = hasDueSnapshot ? stamp() : currentReadAt;
1353
+ const freshCurrent = hasDueSnapshot ? await readCurrentJson(storage, currentJsonKey, signalOpts) : void 0;
1354
+ const fenceCurrent = freshCurrent?.json ?? current;
1355
+ const fenceReadAt = freshCurrent?.json !== void 0 ? freshReadAt : currentReadAt;
1356
+ const fenceGeneration = fenceCurrent.generation ?? "-";
1357
+ const fenceFloor = logSeqStartOf(fenceCurrent);
1358
+ const rescuedKeys = /* @__PURE__ */ new Set();
1359
+ const staleGenerationKeys = /* @__PURE__ */ new Set();
1360
+ const evictedKeys = /* @__PURE__ */ new Set();
1361
+ for (const candidate of sweepCandidates) {
1362
+ if (candidate.reason === "orphan-content") {
1363
+ evictedKeys.add(candidate.key);
1364
+ continue;
1365
+ }
1366
+ if (candidate.reason === "stale-log" && parseSeqFromCanonicalLogKey(candidate.key, collectionPrefix) === null) {
1367
+ evictedKeys.add(candidate.key);
1368
+ continue;
1369
+ }
1370
+ if (candidate.reason === "orphan-snapshot" && parseMaxSeqFromCanonicalSnapshotKey(candidate.key, collectionPrefix) === null) {
1371
+ evictedKeys.add(candidate.key);
1372
+ continue;
1373
+ }
1374
+ if ((candidate.generation ?? "-") !== fenceGeneration) {
1375
+ staleGenerationKeys.add(candidate.key);
1376
+ continue;
1377
+ }
1378
+ if (candidate.reason === "orphan-snapshot" && candidate.key === freshCurrent?.json.snapshot) {
1379
+ rescuedKeys.add(candidate.key);
1380
+ continue;
1381
+ }
1382
+ if (candidate.reason === "stale-log") {
1383
+ const seq = parseSeqFromCanonicalLogKey(candidate.key, collectionPrefix);
1384
+ if (seq !== null && seq >= fenceFloor) rescuedKeys.add(candidate.key);
1385
+ continue;
1386
+ }
1387
+ }
1388
+ const droppedKeys = /* @__PURE__ */ new Set([
1389
+ ...staleGenerationKeys,
1390
+ ...rescuedKeys,
1391
+ ...evictedKeys
1392
+ ]);
1393
+ const toSweep = [];
1394
+ const remaining = [];
1395
+ for (const cand of sweepCandidates) {
1396
+ if (droppedKeys.has(cand.key)) continue;
1397
+ if (toSweep.length < maxSweeps && Date.parse(cand.due_at) <= nowMs) {
1398
+ if (cand.reason === "orphan-snapshot") {
1399
+ const maxSeq = parseMaxSeqFromCanonicalSnapshotKey(cand.key, collectionPrefix);
1400
+ if (maxSeq === null || maxSeq >= (freshCurrent?.json.log_seq_start ?? 0)) {
1401
+ remaining.push(cand);
1402
+ continue;
1403
+ }
1404
+ }
1405
+ toSweep.push(cand);
1406
+ } else remaining.push(cand);
1407
+ }
1408
+ const sweepBudgetMillis = grace * GC_PASS_GRACE_FRACTION;
1409
+ const swept = [];
1410
+ for (let start = 0; start < toSweep.length; start += 100) {
1411
+ if (grace > 0 && elapsedSince(fenceReadAt) > sweepBudgetMillis) break;
1412
+ const batch = toSweep.slice(start, start + 100);
1413
+ await Promise.all(batch.map((c) => storage.delete(c.key, signalOpts)));
1414
+ swept.push(...batch);
1415
+ }
1416
+ const abandonedCount = toSweep.length - swept.length;
1417
+ const sweptKeys = /* @__PURE__ */ new Set([...swept.map((candidate) => candidate.key), ...droppedKeys]);
1418
+ const lastSweptAt = swept.length > 0 ? now().toISOString() : "";
1419
+ const markedSummary = { orphan_snapshot: markedOrphanSnapshot };
1420
+ let pendingDepth;
1421
+ try {
1422
+ pendingDepth = (await casUpdateGcPending(storage, pendingKey, (latest) => mergeGcPending(latest, {
1423
+ sweptKeys,
1424
+ newCandidates,
1425
+ lastSweptAt,
1426
+ maxCandidates: GC_MAX_PENDING_CANDIDATES
1427
+ }), signalOpts)).json.candidates.length;
1428
+ } catch (error) {
1429
+ if (isWriteConflict(error)) pendingDepth = remaining.length + abandonedCount;
1430
+ else throw error;
1431
+ }
1432
+ const labels = { collection: collectionName };
1433
+ const metrics = ctxMetrics();
1434
+ metrics.gauge("db.orphan.candidate_count", pendingDepth, labels);
1435
+ metrics.gauge("db.gc.entries_swept_per_second", swept.length, labels);
1436
+ if (swept.length > 0) {
1437
+ const byReason = /* @__PURE__ */ new Map();
1438
+ for (const c of swept) byReason.set(c.reason, (byReason.get(c.reason) ?? 0) + 1);
1439
+ for (const [reason, count] of byReason) metrics.counter("db.gc.swept_total", count, {
1440
+ collection: collectionName,
1441
+ reason
1442
+ });
1443
+ }
1444
+ if (staleGenerationKeys.size > 0) metrics.counter("db.gc.dropped_total", staleGenerationKeys.size, {
1445
+ collection: collectionName,
1446
+ cause: "stale-generation"
1447
+ });
1448
+ if (rescuedKeys.size > 0) metrics.counter("db.gc.dropped_total", rescuedKeys.size, {
1449
+ collection: collectionName,
1450
+ cause: "still-live"
1451
+ });
1452
+ return {
1453
+ marked: markedSummary,
1454
+ swept: swept.length,
1455
+ dropped: {
1456
+ stale_generation: staleGenerationKeys.size,
1457
+ still_live: rescuedKeys.size
1458
+ },
1459
+ pendingDepth
1460
+ };
1461
+ };
1462
+ /**
1463
+ * `Storage.list` options for one bounded rotation window: at most
1464
+ * `maxKeys` keys, resuming strictly after `cursor` when the ledger
1465
+ * carries one. `maxKeys` is a hard cross-page total on every adapter
1466
+ * (`docs/spec/storage-compatibility.md`), which is what makes
1467
+ * "yielded fewer than we asked for ⇒ end of keyspace" a sound wrap
1468
+ * test. `startAfter` is strict-greater on the key VALUE, so a cursor
1469
+ * naming a key this pass already deleted still resumes correctly —
1470
+ * never probe whether it still exists.
1471
+ */
1472
+ const listWindow = (maxKeys, cursor, signal) => ({
1473
+ maxKeys,
1474
+ ...cursor !== void 0 && { startAfter: cursor },
1475
+ ...signal !== void 0 && { signal }
1476
+ });
1477
+ /**
1478
+ * `maxKeys` for the orphan-snapshot mark LIST: `maxMarks` plus every key
1479
+ * the pass is certain to skip without marking — the `pendingSnapshotKeys`
1480
+ * already in the ledger under `snapshot/L9/` and the one live
1481
+ * `current.snapshot`. Without the widening, a ledger cohort waiting out
1482
+ * its grace fills the lex-first window and marking stalls at `maxMarks`
1483
+ * per grace period.
1484
+ *
1485
+ * Capped at {@link GC_MARK_LIST_PAGE_KEYS} so the widening never adds a
1486
+ * full LIST page: a pass with `maxMarks` at or under one page fits one
1487
+ * page request unless the provider truncates short. The cap is never
1488
+ * below `maxMarks`, so a bounded pass scans at least what it always did.
1489
+ */
1490
+ const markWindowKeys = (maxMarks, pendingSnapshotKeys) => Math.max(maxMarks, Math.min(maxMarks + pendingSnapshotKeys + 1, GC_MARK_LIST_PAGE_KEYS));
1491
+ /**
1492
+ * Parse the exact canonical `log/<seq>.json` key for this collection.
1493
+ * Returns `null` for another prefix, malformed or noncanonical decimal,
1494
+ * or a sequence outside JavaScript's safe-integer range.
1495
+ */
1496
+ const parseSeqFromCanonicalLogKey = (key, collectionPrefix) => {
1497
+ const logPrefix = `${collectionPrefix}/log/`;
1498
+ if (!key.startsWith(logPrefix)) return null;
1499
+ const match = /^(\d+)\.json$/.exec(key.slice(logPrefix.length));
1500
+ if (match === null) return null;
1501
+ const seq = Number(match[1]);
1502
+ return Number.isSafeInteger(seq) && seq >= 0 && logObjectKey(collectionPrefix, seq) === key ? seq : null;
1503
+ };
1504
+ /**
1505
+ * Parse the exclusive `max_seq` from the exact key shape emitted by
1506
+ * `snapshotKey`. Unknown levels/layouts and invalid ranges stay opaque: GC
1507
+ * never deletes the object and never retains its candidate in the bounded
1508
+ * ledger.
1509
+ */
1510
+ const parseMaxSeqFromCanonicalSnapshotKey = (key, collectionPrefix) => {
1511
+ const snapshotPrefix = `${collectionPrefix}/snapshot/L9/`;
1512
+ if (!key.startsWith(snapshotPrefix)) return null;
1513
+ const match = /^(\d{12})-(\d{12})-[0-9a-f]{64}\.json$/.exec(key.slice(snapshotPrefix.length));
1514
+ if (match === null) return null;
1515
+ const minSeq = Number(match[1]);
1516
+ const maxSeq = Number(match[2]);
1517
+ return minSeq <= maxSeq ? maxSeq : null;
1518
+ };
1519
+ /**
1520
+ * Anchor `due_at` on the MARK: `now() + graceMs`. Grace measures the
1521
+ * writer-retry window from when we judged a key dead, which is
1522
+ * unrelated to when the object was written.
1523
+ *
1524
+ * Never anchor on the object's own timestamp. Doing so made the
1525
+ * effective grace `max(0, graceMs − object age)` — zero past the
1526
+ * 7-day default, for exactly the old objects GC marks. It read a
1527
+ * `lastModified` that only the S3/GCS/R2 adapters populated, so the
1528
+ * suite's backends showed a full window and no test could see it.
1529
+ * `StorageListEntry` no longer carries a timestamp; `gc.test.ts`
1530
+ * still pins the behaviour against an entry that fakes one.
1531
+ *
1532
+ * Called per candidate, not hoisted per pass, so the local-clock
1533
+ * backends keep their exact previous horizon.
1534
+ */
1535
+ const computeDueAt = (now, graceMs) => new Date(now().getTime() + graceMs).toISOString();
1536
+ // packages/server/src/log-retention.ts
1537
+ /**
1538
+ * Sequence-based log retention.
1539
+ *
1540
+ * Log keys are derivable, so retirement uses a half-open sequence range rather
1541
+ * than LIST-based discovery. This module computes the range and owns the
1542
+ * CAS-then-delete retirement pass. Every maintenance trigger runs it through
1543
+ * the shared `retireLogs` helper in `maintenance.ts`: `runScheduledMaintenance`
1544
+ * after its GC phase, and `runBoundedMaintenance` on the hard-GC early-return
1545
+ * path and as its final step.
1546
+ */
1547
+ /** Compute the budgeted prefix of the currently retirable log range. */
1548
+ const computeRetirableRange = (current, opts) => {
1549
+ const window = opts?.window ?? 1024;
1550
+ const maxDeletes = opts?.maxDeletes ?? 20;
1551
+ const liveFloor = logSeqStartOf(current);
1552
+ const start = certifiedDeleteFloor(current);
1553
+ const boundary = Math.min(liveFloor - window, liveFloor);
1554
+ return {
1555
+ start,
1556
+ end: Math.max(start, Math.min(boundary, start + maxDeletes))
1557
+ };
1558
+ };
1559
+ /**
1560
+ * Delete a budgeted, computed slice of the stale log prefix and advance
1561
+ * `log_delete_floor` to match. Sequence-based: log keys are derivable, so this
1562
+ * never LISTs.
1563
+ *
1564
+ * **The authorized range is computed inside the CAS mutator, against the state
1565
+ * the CAS validates — do not hoist it out.** {@link casUpdateCurrentJson}
1566
+ * performs its own read and CASes against *that* etag, so a range computed from
1567
+ * an earlier read is a plan the CAS never validated. Computing it in the mutator
1568
+ * makes plan and validation atomic: whatever floor this call publishes is the
1569
+ * floor its own DELETEs are authorized by. If the fresh state yields an empty
1570
+ * range (a `restore --force` reseed lowered `log_seq_start` — the one writer
1571
+ * allowed to, `restore.ts:191-206`), the pass aborts with `WriteConflict` and zero
1572
+ * DELETEs rather than publishing a floor above the live one.
1573
+ *
1574
+ * **CAS before deleting, never after.** Every floor this function publishes
1575
+ * satisfies `end <= log_seq_start - window`, where `window` is the *effective*
1576
+ * window — {@link LOG_RETENTION_SEQ_WINDOW} by default, or `opts.window` when
1577
+ * a caller overrides it (via {@link computeRetirableRange}, which also clamps
1578
+ * a malformed stored floor per `docs/spec/sync-protocol.md` invariant 12).
1579
+ * That bound holds only at the default window: `opts.window` is a test seam
1580
+ * that can shrink or erase the folded entries the window keeps readable for
1581
+ * a windowed commit and steepen the retirement rate it limits (this module's
1582
+ * own `{window: 0}` tests push the floor to `log_seq_start` exactly).
1583
+ * `log_delete_floor` is monotone under the transition validator regardless of
1584
+ * `window`. So by the time a slot is physically deleted, a durable
1585
+ * certificate that it is gone already exists — which is what makes
1586
+ * `log_delete_floor` usable as a witness of "reclaimed" rather than "folded".
1587
+ * A crash between the CAS and the end of the DELETE loop leaks the remaining
1588
+ * slice permanently below the newly-advanced floor: deliberate, and the
1589
+ * fail-safe direction this program picked — leak, never corruption.
1590
+ *
1591
+ * The writer-side counterpart lives on the commit path, not here.
1592
+ * {@link LOG_RETENTION_SEQ_WINDOW} is a cost margin and a rate limit, never a
1593
+ * fence — see its JSDoc. What stops a paused or uncertain writer's create from
1594
+ * being acknowledged in a slot this pass has already retired is
1595
+ * `Writer#assertCommitAboveDeleteFloor`, which re-reads the manifest after the
1596
+ * committing create resolves and fails a sub-floor `seq` with
1597
+ * `BaerlyError{code:"AmbiguousCommit"}`. See
1598
+ * `docs/adr/002-ephemeral-coordination.md` § Closed paths for the two
1599
+ * approaches that were tried and rejected, and why that check is what remains.
1600
+ *
1601
+ * @param opts.signal Threaded to every storage call this makes (the gate
1602
+ * read, the CAS's own read + write, and each DELETE in the loop) — an
1603
+ * already-aborted signal, or one aborted mid-call, rejects the in-flight
1604
+ * {@link Storage} operation.
1605
+ * @param opts.window Test seam that overrides {@link LOG_RETENTION_SEQ_WINDOW}.
1606
+ * NOT a production tuning knob — do not promote this to an env var the way
1607
+ * `BAERLY_MAINTENANCE_*` tunes the fold/GC budgets. Shrinking it (this
1608
+ * module's own tests use `{window: 0}`) erases the pre-image reach and
1609
+ * steepens the retirement rate described above; production call sites
1610
+ * should omit it and take the default.
1611
+ * @param opts.maxDeletes Test seam that overrides
1612
+ * {@link LOG_RETENTION_MAX_DELETES_PER_TICK}. Same caveat as `opts.window`:
1613
+ * a scoped override for exercising the budget boundary in tests, not a
1614
+ * knob meant to reach a config surface.
1615
+ * @throws BaerlyError{code:"WriteConflict"} if the floor CAS loses to another
1616
+ * `current.json` writer, or if the fresh state authorizes nothing. The
1617
+ * maintenance call sites' shared `retireLogs` helper (`maintenance.ts`)
1618
+ * swallows exactly this code and re-throws everything else, matching how
1619
+ * `WriteConflict` from `compact()` / `runGc()` is treated at every call site;
1620
+ * returning it unwrapped here is what keeps that policy in one place.
1621
+ * @throws BaerlyError{code:"Internal"} if the floor CAS completes without
1622
+ * having authorized the range it published — a wiring tripwire, not a
1623
+ * runtime state. `retireLogs` re-throws it into `runBoundedMaintenance`'s
1624
+ * outer catch (`db.maintenance.unexpected_error_total`), so the failure is
1625
+ * observable rather than silent.
1626
+ */
1627
+ async function retireLogRange(storage, currentJsonKey, opts) {
1628
+ const readOpts = opts?.signal !== void 0 ? { signal: opts.signal } : void 0;
1629
+ const read = await readCurrentJson(storage, currentJsonKey, readOpts);
1630
+ if (read === null) return { deleted: 0 };
1631
+ const gate = computeRetirableRange(read.json, opts);
1632
+ if (gate.start >= gate.end) return { deleted: 0 };
1633
+ let authorized;
1634
+ const cas = await casUpdateCurrentJson(storage, currentJsonKey, (current) => {
1635
+ authorized = computeRetirableRange(current, opts);
1636
+ if (authorized.start >= authorized.end) throw new BaerlyError("WriteConflict", `retireLogRange: ${currentJsonKey} authorizes no retirable range at CAS time; a concurrent writer moved log_seq_start`);
1637
+ return {
1638
+ ...current,
1639
+ log_delete_floor: authorized.end
1640
+ };
1641
+ }, readOpts);
1642
+ if (authorized === void 0 || logDeleteFloorOf(cas.json) !== authorized.end) {
1643
+ const published = logDeleteFloorOf(cas.json);
1644
+ const authorizedEnd = authorized === void 0 ? "none" : String(authorized.end);
1645
+ throw new BaerlyError("Internal", `retireLogRange: ${currentJsonKey}: the floor CAS published ${String(published)} against authorized end ${authorizedEnd}; refusing to DELETE a range the CAS never validated`);
1646
+ }
1647
+ const range = authorized;
1648
+ const { prefix: collectionPrefix } = collectionFromCurrentJsonKey(currentJsonKey);
1649
+ await Promise.all(Array.from({ length: range.end - range.start }, (_, i) => storage.delete(logObjectKey(collectionPrefix, range.start + i), readOpts)));
1650
+ return { deleted: range.end - range.start };
1651
+ }
1652
+ // packages/server/src/maintenance.ts
1653
+ /**
1654
+ * Maintenance passes over one collection. `runScheduledMaintenance` is the
1655
+ * published opt-in scheduled pass (addressed by collection, sized by host
1656
+ * tier); `runMaintenancePass` is the internal composition it resolves to,
1657
+ * which the adapters, CLI, bench and tests drive with per-phase knobs;
1658
+ * `runBoundedMaintenance` is the in-band write-tick runner.
1659
+ *
1660
+ * Every pass is a single attempt: `compact()` and `runGc()` are
1661
+ * CAS-protected, so a pass cut short is retried safely by the next one.
1662
+ * The caller schedules the next pass; nothing here loops or retries.
1663
+ */
1664
+ /**
1665
+ * One log-retirement pass: run {@link retireLogRange} and emit its
1666
+ * counter. Shared by every maintenance trigger that retires stale logs
1667
+ * (`runScheduledMaintenance` and both retirement points inside
1668
+ * `runBoundedMaintenance`), so the metric name, option threading, and
1669
+ * error policy cannot drift between call sites.
1670
+ *
1671
+ * Error policy — deliberately NOT a bare swallow: `WriteConflict` (the floor
1672
+ * CAS lost to another writer, or a concurrent fold moved `log_seq_start`)
1673
+ * is routine contention, swallowed here and retried by the next pass.
1674
+ * Anything else is re-thrown for the caller's own error path, matching
1675
+ * how `compact()` / `runGc()` failures are treated at every call site:
1676
+ * `runBoundedMaintenance`'s outer catch counts
1677
+ * `db.maintenance.unexpected_error_total` and logs the stack, and
1678
+ * `runScheduledMaintenance` propagates per its documented "errors
1679
+ * propagate" contract. Retirement is the only mechanism bounding the
1680
+ * steady-state log-object count — a persistent unexpected failure must
1681
+ * not fail silently while objects accumulate unbounded.
1682
+ */
1683
+ const retireLogs = async (storage, currentJsonKey, opts) => {
1684
+ const { name: collection } = collectionFromCurrentJsonKey(currentJsonKey);
1685
+ try {
1686
+ const retired = await retireLogRange(storage, currentJsonKey, {
1687
+ ...opts?.logRetention,
1688
+ ...opts?.signal !== void 0 && { signal: opts.signal }
1689
+ });
1690
+ ctxMetrics().counter("db.log_retention.deleted_total", retired.deleted, { collection });
1691
+ return retired.deleted;
1692
+ } catch (error) {
1693
+ if (isWriteConflict(error)) return 0;
1694
+ throw error;
1695
+ }
1696
+ };
1697
+ /**
1698
+ * One maintenance pass over one collection, addressed by its `current.json`
1699
+ * key: `compact()` then `runGc()` (in that order; the compactor's advance
1700
+ * of `log_seq_start` produces the stale-log candidates the GC then marks),
1701
+ * then log retirement. With {@link CLOUDFLARE_FREE_TIER} the whole pass is
1702
+ * at most 94 storage calls, 282 with every call retried, which fits the 900
1703
+ * a Workers Free invocation may spend through the R2 binding but not the 45
1704
+ * it may spend through `fetch` (see {@link CLOUDFLARE_FREE_TIER}). The
1705
+ * request ledger refuses any call past the invocation's limit before it is
1706
+ * sent, so a pass never exceeds the limit.
1707
+ *
1708
+ * `minEntriesToCompact` defaults to {@link SCHEDULED_MIN_ENTRIES_TO_COMPACT}
1709
+ * (1) here, deliberately NOT `compact()`'s own default (100) or the
1710
+ * write-tick floor ({@link WRITE_TICK_MIN_ENTRIES_TO_COMPACT}, 50), both of
1711
+ * which exist to keep an in-band write from thrashing snapshot rewrites. A
1712
+ * scheduler that fires has already decided it is time to work, so the
1713
+ * scheduled path drains the live tail to zero rather than parking it in a
1714
+ * dead zone between a count floor and the per-entry GET cost every read
1715
+ * pays. An explicit `options.compact.minEntriesToCompact` suppresses this
1716
+ * default; {@link CLOUDFLARE_FREE_TIER} carries 20, which keeps
1717
+ * `minEntriesToCompact <= P` for its bounded tail probe.
1718
+ *
1719
+ * Errors propagate; `WriteConflict` from retirement is swallowed as
1720
+ * routine contention (see `retireLogs`).
1721
+ *
1722
+ * @internal
1723
+ */
1724
+ const runMaintenancePass = async (args, options = {}) => {
1725
+ return {
1726
+ compact: await compactPhase(args, options),
1727
+ gc: await gcPhase(args, options),
1728
+ retired: await retireLogs(args.storage, args.currentJsonKey, {
1729
+ logRetention: options.logRetention,
1730
+ ...options.signal !== void 0 && { signal: options.signal }
1731
+ })
1732
+ };
1733
+ };
1734
+ /** The pass's `compact()` call, with the scheduled fold floor. */
1735
+ const compactPhase = (args, options) => compact(args, {
1736
+ ...options.compact,
1737
+ ...options.compact?.minEntriesToCompact === void 0 && { minEntriesToCompact: 1 },
1738
+ ...options.signal !== void 0 && { signal: options.signal }
1739
+ });
1740
+ /** The pass's `runGc()` call. */
1741
+ const gcPhase = (args, options) => runGc(args, {
1742
+ ...options.gc,
1743
+ ...options.signal !== void 0 && { signal: options.signal }
1744
+ });
1745
+ const profileToScheduledOptions = (profile, compactMaxTailProbeGets, minEntriesToCompact = 1) => ({
1746
+ compact: {
1747
+ maxEntriesPerRun: profile.maxFoldEntriesPerPass,
1748
+ minEntriesToCompact,
1749
+ ...compactMaxTailProbeGets !== void 0 && { maxTailProbeGets: compactMaxTailProbeGets }
1750
+ },
1751
+ gc: {
1752
+ maxMarksPerRun: profile.gcMaxMarks,
1753
+ maxSweepsPerRun: profile.gcMaxSweeps
1754
+ }
1755
+ });
1756
+ const TIER_OPTIONS = {
1757
+ "cf-free": profileToScheduledOptions(MAINTENANCE_PROFILE_CF_FREE, 25, MAINTENANCE_PROFILE_CF_FREE.maxFoldEntriesPerPass),
1758
+ "cf-paid": profileToScheduledOptions(MAINTENANCE_PROFILE_CF_PAID, CF_PAID_COMPACT_TAIL_PROBE_GETS),
1759
+ node: {}
1760
+ };
1761
+ /**
1762
+ * Run one opt-in scheduled maintenance pass over one collection: fold its
1763
+ * recent writes, delete data nothing references any more, and retire old
1764
+ * log entries. Optional: every write already runs bounded maintenance in
1765
+ * band, so a collection that takes writes maintains itself. A schedule is
1766
+ * for collections served mostly read-only, or to keep folding ahead of
1767
+ * the write tick.
1768
+ *
1769
+ * One call does a bounded amount of work and returns; it never loops or
1770
+ * retries, and it is safe to run concurrently with writes and with other
1771
+ * passes. The caller schedules the next pass. Run one collection per
1772
+ * Cloudflare invocation: shard the cron schedule or persist a collection
1773
+ * cursor instead of looping tenants or collections in one invocation.
1774
+ *
1775
+ * `tier` sizes the pass for its host, in the `BAERLY_MAINTENANCE_PROFILE`
1776
+ * vocabulary: `"cf-free"` fits one Workers Free invocation through the R2
1777
+ * binding, `"cf-paid"` one Workers Paid invocation, and `"node"` (the
1778
+ * default) is unbounded. S3 storage on Workers needs Paid, with
1779
+ * `"cf-paid"`.
1780
+ *
1781
+ * Errors propagate; log them from the cron handler. On Cloudflare an
1782
+ * uncaught error reaches the Workers dashboard.
1783
+ *
1784
+ * @throws BaerlyError code="InvalidConfig" when `app`, `tenant` or
1785
+ * `collection` is not a name `Db.create` / `db.collection` accepts, or
1786
+ * `tier` is not one of the listed values, or when an option this
1787
+ * release no longer accepts is passed.
1788
+ *
1789
+ * @example
1790
+ * ```ts
1791
+ * import { runScheduledMaintenance } from "@gusto/baerly-storage/maintenance";
1792
+ *
1793
+ * const target = { storage, app: "helpdesk", tenant: "acme", collection: "tickets" };
1794
+ *
1795
+ * // Node: one unbounded pass.
1796
+ * const res = await runScheduledMaintenance(target);
1797
+ * console.log("folded", res.folded, "deleted", res.gcDeleted);
1798
+ *
1799
+ * // Cloudflare: one bounded pass per invocation.
1800
+ * await runScheduledMaintenance(target, { tier: "cf-paid" });
1801
+ * ```
1802
+ */
1803
+ const runScheduledMaintenance = async (target, options = {}) => {
1804
+ const { storage, app, tenant, collection } = target;
1805
+ assertNameSegment(app, "app", "runScheduledMaintenance");
1806
+ assertNameSegment(tenant, "tenant", "runScheduledMaintenance");
1807
+ assertNameSegment(collection, "collection", "runScheduledMaintenance");
1808
+ const { tier = "node", signal } = options;
1809
+ const tierOptions = Object.hasOwn(TIER_OPTIONS, tier) ? TIER_OPTIONS[tier] : void 0;
1810
+ if (tierOptions === void 0) throw new BaerlyError("InvalidConfig", `runScheduledMaintenance: tier must be "cf-free", "cf-paid" or "node", got ${JSON.stringify(tier)}`);
1811
+ if (options.phase !== void 0) throw new BaerlyError("InvalidConfig", "runScheduledMaintenance: `phase` was removed in 0.7; each invocation runs one whole maintenance pass — remove the option");
1812
+ const args = {
1813
+ storage,
1814
+ currentJsonKey: `app/${app}/tenant/${tenant}/manifests/${collection}/current.json`
1815
+ };
1816
+ const passOptions = {
1817
+ ...tierOptions,
1818
+ ...signal !== void 0 && { signal }
1819
+ };
1820
+ return summarize(await runMaintenancePass(args, passOptions));
1821
+ };
1822
+ /**
1823
+ * Compaction skips that leave available work unfolded. The scheduled
1824
+ * tiers set no snapshot ceiling, so the over-ceiling `"deferred"` skip
1825
+ * cannot occur on this path.
1826
+ */
1827
+ const DEFERRAL_REASONS = {
1828
+ "cas-lost": "contention",
1829
+ "probe-budget-checkpointed": "budget"
1830
+ };
1831
+ /** Format-neutral summary of one whole pass. */
1832
+ const summarize = ({ compact: compactRes, gc: gcRes, retired }) => {
1833
+ const reason = DEFERRAL_REASONS[compactRes.skippedReason ?? ""];
1834
+ return {
1835
+ folded: compactRes.written ? compactRes.entriesFolded : 0,
1836
+ ...reason !== void 0 && { deferred: { reason } },
1837
+ gcDeleted: gcRes.swept + retired,
1838
+ pending: gcRes.pendingDepth
1839
+ };
1840
+ };
1841
+ /**
1842
+ * Floor-based GC-cadence boundary crossing. Every commit advances the
1843
+ * writer-observed tail by one logical slot; `tail_hint` remains a
1844
+ * lower bound and may be refreshed later by maintenance. The floor test
1845
+ * trips on any interval boundary inside `(prevSeq, nextSeq]`, so it
1846
+ * stays correct whether the observed/probed tail advances by one or
1847
+ * catches up by a larger step.
1848
+ */
1849
+ const crossesGcBoundary = (prevSeq, nextSeq, interval) => Math.floor(prevSeq / interval) !== Math.floor(nextSeq / interval);
1850
+ /**
1851
+ * The write-tick runner's pre-fold projection off STORED figures: the
1852
+ * snapshot it would load is within `C` bytes and `E` rows. It does not
1853
+ * project the pass: `compact()` counts real rows as it applies the range
1854
+ * and folds the longest prefix that stays within `E`, so an update/delete
1855
+ * tail keeps folding at the ceiling and only an entry that would add a row
1856
+ * past `E` stops it. The runner, `baerly inspect` and the backlog bench
1857
+ * share this predicate. Both comparisons are written so a NaN ceiling
1858
+ * fails closed.
1859
+ */
1860
+ const isFoldViable = (snapshotBytes, snapshotRows, ceilings) => snapshotBytes <= ceilings.maxFoldBytes && snapshotRows <= ceilings.maxFoldRows;
1861
+ /**
1862
+ * Resolve the serving host's fold ceilings: `profile` (absent ⇒
1863
+ * {@link MAINTENANCE_PROFILE_CF_FREE}) with `C` overridden by
1864
+ * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` (`maxFoldBytes`). `E` has no
1865
+ * override. The write-tick runner and growth refusal (`capacity.ts`) both
1866
+ * resolve through here, so a refusal and a fold never see different
1867
+ * ceilings.
1868
+ */
1869
+ const resolveFoldCeilings = (profile, maxFoldBytes) => {
1870
+ const resolved = profile ?? MAINTENANCE_PROFILE_CF_FREE;
1871
+ return {
1872
+ maxFoldBytes: maxFoldBytes ?? resolved.maxFoldBytes,
1873
+ maxFoldRows: resolved.maxFoldRows
1874
+ };
1875
+ };
1876
+ /**
1877
+ * Derived live-tail byte size — the ratio TRIGGER input that replaces the
1878
+ * formerly-stored exact byte count. `(observedTail − log_seq_start) ×
1879
+ * mean_entry_bytes`. `observedTail` is a param so write-tick callers can
1880
+ * pass the writer-observed tail and scheduled callers can pass a
1881
+ * probe-discovered true tail. Cold-start (no mean yet) falls back to
1882
+ * {@link MAINTENANCE_COLD_START_ENTRY_BYTES}, never 0 (see that constant).
1883
+ * TRIGGER-only — structurally barred from `foldViable` (the exact-bytes fold
1884
+ * ceiling).
1885
+ */
1886
+ const estimateTailBytes = (current, observedTail) => Math.max(0, observedTail - current.log_seq_start) * (current.mean_entry_bytes ?? 128);
1887
+ /** Derived live-tail bytes over the snapshot's bytes (floored at {@link MAINTENANCE_MIN_LIVE_BYTES}). */
1888
+ const tailRatio = (current, observedTail) => estimateTailBytes(current, observedTail) / Math.max(current.snapshot_bytes, MAINTENANCE_MIN_LIVE_BYTES);
1889
+ /**
1890
+ * The cheap DISPATCH gate the writer calls after a commit — zero
1891
+ * storage ops; it reads the post-commit {@link CurrentJson} already in
1892
+ * scope. Ratio-OR-boundary, WITHOUT the entry floor (the floor is part
1893
+ * of the fold-trigger Gate 1 checked inside {@link runBoundedMaintenance}).
1894
+ * Returning `false` lets the writer skip the dispatch entirely. Ratio
1895
+ * numerator is the DERIVED {@link estimateTailBytes};
1896
+ * `observedTail` threads from the caller (the writer's in-memory observed
1897
+ * tail `seq+1` under single-write commit). Both the boundary check and the
1898
+ * ratio key off `observedTail`, since the stored `tail_hint` is now only a
1899
+ * non-authoritative lower bound (compactor-advanced).
1900
+ */
1901
+ const shouldFireMaintenance = (current, prevSeq, gcInterval, observedTail) => crossesGcBoundary(prevSeq, observedTail, gcInterval) || tailRatio(current, observedTail) >= 1;
1902
+ /**
1903
+ * Human-readable line for a fold-wall deferral. Names both ceilings, which
1904
+ * arm tripped, that `log_seq_start` and log retention are frozen, and the
1905
+ * remedy that actually applies to that arm — the bytes override does
1906
+ * nothing for rows.
1907
+ */
1908
+ const foldDeferredWarning = (f) => {
1909
+ const which = f.gate === "rebuild" ? "rebuilt" : "stored";
1910
+ const rowsTripped = f.gate === "rebuild" ? `the rows arm tripped (the next log entry adds a row past E, or the rebuilt snapshot is over E)` : `the rows arm tripped (snapshot_rows > E)`;
1911
+ const tripped = f.dimension === "bytes" ? `the bytes arm tripped (snapshot_bytes > C)` : rowsTripped;
1912
+ const remedy = f.dimension === "bytes" ? `On Workers Paid set BAERLY_MAINTENANCE_PROFILE=cf-paid (C=${MAINTENANCE_PROFILE_CF_PAID.maxFoldBytes}); on paid Cloudflare / Node you can also raise BAERLY_MAINTENANCE_MAX_FOLD_BYTES — but on Cloudflare a cap above the configured default may exceed an invocation's CPU or memory resources, so such folds may not land. Otherwise, move to a database service (D1 / Postgres).` : `E has no env override, and BAERLY_MAINTENANCE_MAX_FOLD_BYTES does not apply to rows. On Cloudflare, move to Workers Paid and set BAERLY_MAINTENANCE_PROFILE=cf-paid (E=${MAINTENANCE_PROFILE_CF_PAID.maxFoldRows}); on Node (E=${MAINTENANCE_PROFILE_NODE.maxFoldRows}) or past the paid ceiling, split the collection or move to a database service (D1 / Postgres).`;
1913
+ return `baerly-storage: collection "${f.collection}" has stopped compacting — the ${which} snapshot is ${f.snapshot_bytes} bytes / ${f.snapshot_rows} rows against this host's fold ceiling C=${f.ceiling_bytes} bytes, E=${f.ceiling_rows} rows, and ${tripped}. Until it folds again log_seq_start stays at ${f.log_seq_start}, log retention is paused, the live tail (${f.live_log_tail} entries) and the bucket grow without bound, and every read replays the tail. ${remedy} See docs/about/graduation.md.`;
1914
+ };
1915
+ /**
1916
+ * The write-tick maintenance runner: a bounded, single-attempt
1917
+ * composition of {@link compact} and {@link runGc} for one collection,
1918
+ * sized by default to a conservative Cloudflare free-tier CPU budget.
1919
+ *
1920
+ * INVARIANT: a {@link MaintenanceProfile} changes only maintenance rate +
1921
+ * defer threshold — never data/API/query/wire/correctness; reads stay pure.
1922
+ * See `maintenance-profile-equivalence.test.ts`.
1923
+ *
1924
+ * Never throws — the write-tick caller must never see a maintenance
1925
+ * failure. CAS contention is swallowed quietly, and so is a call the
1926
+ * invocation's request ledger refused (each phase is sized from the
1927
+ * ledger's remainder first; see the request-budget note inside, and
1928
+ * `docs/spec/sync-protocol.md` "Per-invocation request budget"); an over-ceiling deferral
1929
+ * is not an error but is signalled loudly (see `signalFoldDeferred`
1930
+ * inside); unexpected throws bump
1931
+ * `db.maintenance.unexpected_error_total`, log a stack, and are
1932
+ * swallowed.
1933
+ *
1934
+ * Control flow (fold-priority with a stateless GC-starvation guard):
1935
+ * 0. `disabled` → skip fold/GC, but still allow the rate-limited
1936
+ * tail_hint refresh that bounds read/write forward-probes.
1937
+ * 1. Read `current.json` once.
1938
+ * 2. Hard-GC starvation boundary (`"single"` only) → GC slice, skip fold.
1939
+ * 3. Gate 1 (ratio AND entry floor, or a forced tick) trips → fold if the pre-fold
1940
+ * projection is viable, else defer and signal. On `"single"` a fold
1941
+ * attempt is this tick's one phase — including one that compact()
1942
+ * deferred after rebuilding, which signals the same way and ends the
1943
+ * tick. A pre-fold defer falls through to Step 4.
1944
+ * 4. Otherwise (or on `"both"`) → GC iff the cadence boundary crossed.
1945
+ *
1946
+ * Steps 0, 2, 3-defer, and 4 all take the rate-limited `tail_hint`
1947
+ * refresh, but the tick publishes the hint AT MOST ONCE — a landed fold
1948
+ * (Step-7 CAS) and the refresh itself both count as that publication.
1949
+ * Ordering matters: Step 3's defer refreshes and then falls through to
1950
+ * Step 4, so without the shared guard that one tick would CAS
1951
+ * `current.json` twice with identical bytes.
1952
+ */
1953
+ const runBoundedMaintenance = async (args, options) => {
1954
+ const { storage, currentJsonKey, prevSeq } = args;
1955
+ const profile = options?.profile ?? MAINTENANCE_PROFILE_CF_FREE;
1956
+ const { maxFoldEntriesPerPass, gcMaxMarks, gcMaxSweeps, gcInterval } = profile;
1957
+ const forceFold = args.forceFold === true;
1958
+ const minEntriesToCompact = forceFold ? 1 : options?.minEntriesToCompact ?? 50;
1959
+ const phasesPerTick = options?.phasesPerTick ?? "single";
1960
+ const signal = options?.signal;
1961
+ const ceilings = resolveFoldCeilings(profile, args.maxFoldBytes);
1962
+ const C = ceilings.maxFoldBytes;
1963
+ const E = ceilings.maxFoldRows;
1964
+ const { prefix: collectionPrefix, name: collection } = collectionFromCurrentJsonKey(currentJsonKey);
1965
+ const gcOpts = {
1966
+ maxMarksPerRun: gcMaxMarks,
1967
+ maxSweepsPerRun: gcMaxSweeps,
1968
+ ...signal !== void 0 && { signal },
1969
+ ...options?.gcGraceMillis !== void 0 && { graceMillis: options.gcGraceMillis },
1970
+ ...options?.now !== void 0 && { now: options.now }
1971
+ };
1972
+ const ledger = getCurrentContext()?.ledger;
1973
+ const requestsLeft = () => ledger?.storageRemaining() ?? 1e400;
1974
+ const skipForBudget = (phase) => {
1975
+ ctxMetrics().counter("db.maintenance.request_budget_skipped_total", 1, {
1976
+ collection,
1977
+ phase
1978
+ });
1979
+ };
1980
+ const retireWithinBudget = async () => {
1981
+ const deletes = Math.floor((requestsLeft() - 7) / 3);
1982
+ if (deletes < 1) {
1983
+ skipForBudget("retire");
1984
+ return;
1985
+ }
1986
+ const logRetention = options?.logRetention;
1987
+ const maxDeletes = logRetention?.maxDeletes ?? 20;
1988
+ await retireLogs(storage, currentJsonKey, {
1989
+ logRetention: deletes < maxDeletes ? {
1990
+ ...logRetention,
1991
+ maxDeletes: deletes
1992
+ } : logRetention,
1993
+ ...signal !== void 0 && { signal }
1994
+ });
1995
+ };
1996
+ try {
1997
+ const read = await readCurrentJson(storage, currentJsonKey, signal !== void 0 ? { signal } : void 0);
1998
+ if (read === null) return;
1999
+ const current = read.json;
2000
+ const snapshotBytes = current.snapshot_bytes;
2001
+ const snapshotRows = current.snapshot_rows;
2002
+ const logSeqStart = current.log_seq_start;
2003
+ const probeFloor = Math.max(logSeqStart, current.tail_hint);
2004
+ let nextSeq;
2005
+ if (args.observedTail !== void 0) nextSeq = Math.max(args.observedTail, probeFloor);
2006
+ else nextSeq = (await probeTailFrom(storage, collectionPrefix, probeFloor, signal !== void 0 ? { signal } : void 0)).tail;
2007
+ const ratio = tailRatio(current, nextSeq);
2008
+ const foldAtTailEntries = options?.foldAtTailEntries;
2009
+ const gate1 = forceFold || foldAtTailEntries !== void 0 && nextSeq - logSeqStart >= foldAtTailEntries || ratio >= 1 && nextSeq - logSeqStart >= minEntriesToCompact;
2010
+ const foldViable = isFoldViable(snapshotBytes, snapshotRows, ceilings);
2011
+ const gcDue = crossesGcBoundary(prevSeq, nextSeq, gcInterval);
2012
+ let tailHintPublished = false;
2013
+ const refreshTailHintIfNeeded = async (stampWarnedSeq = false) => {
2014
+ if (!stampWarnedSeq) {
2015
+ if (tailHintPublished) return;
2016
+ if (nextSeq - current.tail_hint < 128) return;
2017
+ }
2018
+ tailHintPublished = true;
2019
+ if (requestsLeft() < 2) {
2020
+ skipForBudget("tail_hint");
2021
+ return;
2022
+ }
2023
+ try {
2024
+ await casUpdateCurrentJson(storage, currentJsonKey, (c) => ({
2025
+ ...c,
2026
+ tail_hint: Math.max(c.tail_hint, nextSeq),
2027
+ ...stampWarnedSeq && { last_warned_seq: nextSeq }
2028
+ }), signal !== void 0 ? { signal } : void 0);
2029
+ } catch {}
2030
+ };
2031
+ /**
2032
+ * The one fold-wall deferral signal, shared by both gates so a
2033
+ * deferral counts once and reads the same wherever it closed:
2034
+ *
2035
+ * - `db.compaction.deferred_total` (labels `collection`, `dimension`,
2036
+ * `gate`) plus `db.compaction.deferred_{bytes,rows}_total` — distinct
2037
+ * names, because the canonical line keys counters by name alone and
2038
+ * drops labels.
2039
+ * - A `fold_deferred` structured warning through the adapter's
2040
+ * {@link MaintenanceDispatch.warn} sink, carrying the human text as
2041
+ * `detail` — or, with no sink or one that throws, that text as a
2042
+ * `console.warn` line. Rate-limited by the SHARED `current.json.last_warned_seq` (not a
2043
+ * per-isolate Set — a fresh isolate must honour it). A collection
2044
+ * that has never warned warns on its first deferral. On Cloudflare
2045
+ * the tick runs in `ctx.waitUntil` after the canonical line flushed,
2046
+ * so the log record is the only signal an operator sees.
2047
+ * - The bounded `tail_hint` refresh (HR-2): a deferring collection
2048
+ * never reaches compact()'s Step-7 CAS, so without it every read
2049
+ * would re-walk the whole growing tail. Write-tick only; reads stay
2050
+ * pure.
2051
+ */
2052
+ const signalFoldDeferred = async (d) => {
2053
+ const metrics = ctxMetrics();
2054
+ metrics.counter("db.compaction.deferred_total", 1, {
2055
+ collection,
2056
+ dimension: d.dimension,
2057
+ gate: d.gate
2058
+ });
2059
+ metrics.counter(d.dimension === "bytes" ? "db.compaction.deferred_bytes_total" : "db.compaction.deferred_rows_total", 1, {
2060
+ collection,
2061
+ gate: d.gate
2062
+ });
2063
+ const warnDue = current.last_warned_seq === void 0 || nextSeq - current.last_warned_seq >= 1e3;
2064
+ if (warnDue) {
2065
+ const fields = {
2066
+ collection,
2067
+ dimension: d.dimension,
2068
+ gate: d.gate,
2069
+ snapshot_bytes: d.snapshotBytes,
2070
+ snapshot_rows: d.snapshotRows,
2071
+ ceiling_bytes: C,
2072
+ ceiling_rows: E,
2073
+ live_log_tail: nextSeq - logSeqStart,
2074
+ log_seq_start: logSeqStart
2075
+ };
2076
+ const detail = foldDeferredWarning(fields);
2077
+ const sink = getCurrentContext()?.maintenance?.warn;
2078
+ let delivered = false;
2079
+ if (sink !== void 0) try {
2080
+ sink("fold_deferred", {
2081
+ ...fields,
2082
+ detail
2083
+ });
2084
+ delivered = true;
2085
+ } catch {}
2086
+ if (!delivered) console.warn(detail);
2087
+ }
2088
+ await refreshTailHintIfNeeded(warnDue);
2089
+ };
2090
+ const runGcAndRefreshTailHint = async () => {
2091
+ const sweeps = requestsLeft() - 6;
2092
+ if (sweeps < 0) skipForBudget("gc");
2093
+ else await runGc({
2094
+ storage,
2095
+ currentJsonKey
2096
+ }, sweeps < gcMaxSweeps ? {
2097
+ ...gcOpts,
2098
+ maxSweepsPerRun: sweeps
2099
+ } : gcOpts);
2100
+ await refreshTailHintIfNeeded();
2101
+ };
2102
+ try {
2103
+ if (args.disabled === true) {
2104
+ await refreshTailHintIfNeeded();
2105
+ return;
2106
+ }
2107
+ const hardGc = crossesGcBoundary(prevSeq, nextSeq, gcInterval * 4);
2108
+ if (phasesPerTick === "single" && hardGc) {
2109
+ await runGcAndRefreshTailHint();
2110
+ await retireWithinBudget();
2111
+ return;
2112
+ }
2113
+ const foldFits = requestsLeft() >= 5 + Math.min(maxFoldEntriesPerPass, Math.max(0, nextSeq - logSeqStart));
2114
+ if (gate1 && foldViable && !foldFits) skipForBudget("fold");
2115
+ else if (gate1) {
2116
+ if (foldViable) {
2117
+ const foldRes = await compact({
2118
+ storage,
2119
+ currentJsonKey
2120
+ }, {
2121
+ maxEntriesPerRun: maxFoldEntriesPerPass,
2122
+ minEntriesToCompact: foldAtTailEntries === void 0 ? minEntriesToCompact : Math.min(minEntriesToCompact, foldAtTailEntries),
2123
+ ceilingBytes: C,
2124
+ ceilingEntries: E,
2125
+ knownTail: nextSeq,
2126
+ ...signal !== void 0 && { signal }
2127
+ });
2128
+ if (foldRes.written) tailHintPublished = true;
2129
+ if (foldRes.deferral !== void 0) await signalFoldDeferred({
2130
+ gate: "rebuild",
2131
+ dimension: foldRes.deferral.dimension,
2132
+ snapshotBytes: foldRes.deferral.snapshotBytes,
2133
+ snapshotRows: foldRes.deferral.snapshotRows
2134
+ });
2135
+ if (phasesPerTick === "single") return;
2136
+ } else await signalFoldDeferred({
2137
+ gate: "pre-fold",
2138
+ dimension: snapshotBytes > C ? "bytes" : "rows",
2139
+ snapshotBytes,
2140
+ snapshotRows
2141
+ });
2142
+ }
2143
+ if (gcDue) await runGcAndRefreshTailHint();
2144
+ await retireWithinBudget();
2145
+ } finally {
2146
+ await refreshTailHintIfNeeded();
2147
+ }
2148
+ } catch (error) {
2149
+ if (isWriteConflict(error)) return;
2150
+ if (error instanceof BaerlyError && error.code === "CapacityExceeded" && error.cause?.refused === true) {
2151
+ ctxMetrics().counter("db.maintenance.request_budget_refused_total", 1, { collection });
2152
+ return;
2153
+ }
2154
+ ctxMetrics().counter("db.maintenance.unexpected_error_total", 1, { collection });
2155
+ console.error(error);
2156
+ }
2157
+ };
2158
+ /**
2159
+ * Dispatch one write-tick {@link runBoundedMaintenance} through the
2160
+ * request's {@link MaintenanceDispatch}: inline and awaited by default,
2161
+ * `ctx.waitUntil` on Cloudflare. Never throws: the tick swallows its own
2162
+ * failures, and a failing dispatcher bumps
2163
+ * `db.write.maintenance_dispatch_failed_total`. The writer calls it after
2164
+ * a commit; a write refused with `MaintenancePending` calls it with
2165
+ * `forceFold` and nothing committed (`prevSeq === observedTail`).
2166
+ */
2167
+ const dispatchWriteTick = async (args) => {
2168
+ const maint = getCurrentContext()?.maintenance;
2169
+ const dispatch = maint?.dispatch ?? dispatchInlineAwaited;
2170
+ try {
2171
+ await dispatch(() => runBoundedMaintenance({
2172
+ storage: args.storage,
2173
+ currentJsonKey: args.currentJsonKey,
2174
+ prevSeq: args.prevSeq,
2175
+ observedTail: args.observedTail,
2176
+ ...maint?.disabled === true && { disabled: true },
2177
+ ...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes },
2178
+ ...args.forceFold === true && { forceFold: true }
2179
+ }, maint?.options).then(() => {}, () => {}));
2180
+ } catch {
2181
+ ctxMetrics().counter("db.write.maintenance_dispatch_failed_total", 1, { collection: args.collection });
2182
+ }
2183
+ };
2184
+ /**
2185
+ * Default maintenance dispatcher: run the task inline and await it.
2186
+ * Adapters that can keep running after the response (Cloudflare:
2187
+ * `ctx.waitUntil`) override this with a fire-and-forget variant that
2188
+ * returns `void`.
2189
+ */
2190
+ const dispatchInlineAwaited = (task) => task();
2191
+ /**
2192
+ * Parse the two host-agnostic ops-plane env vars into the
2193
+ * {@link MaintenanceDispatch} overrides. Shared by every host adapter so the
2194
+ * cross-host contract has one source of truth.
2195
+ *
2196
+ * `maxFoldBytes` (`C`) is `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` written as a
2197
+ * plain positive decimal integer (`/^[1-9][0-9]*$/`, at most
2198
+ * `Number.MAX_SAFE_INTEGER`), or undefined when unset or `""` (the active
2199
+ * profile's default applies). Anything else throws, untrimmed: `" 1024"`,
2200
+ * `"0x400"`, `"1e6"`, `"1.5"`, `"8mb"`. A unit-suffixed or mistyped value
2201
+ * would otherwise run silently at the default ceiling; zero or negative
2202
+ * would make `snapshot_bytes <= C` false forever, so the fold would defer
2203
+ * on every tick and the live tail would grow unbounded.
2204
+ *
2205
+ * `disabled` reads `BAERLY_MAINTENANCE_DISABLE`, untrimmed, against a closed,
2206
+ * case-insensitive vocabulary: unset, `""`, `"0"`, `"false"` → `false`;
2207
+ * `"1"`, `"true"` → `true`; anything else throws. The prior truthy-if-
2208
+ * non-empty parsing silently disabled maintenance on `"no"` / `"off"` —
2209
+ * the two most natural ways an operator would try to spell "don't disable".
2210
+ *
2211
+ * @throws {BaerlyError} `InvalidConfig` for a
2212
+ * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` that is not a plain positive decimal
2213
+ * integer, or a `BAERLY_MAINTENANCE_DISABLE`
2214
+ * value outside the closed vocabulary above.
2215
+ */
2216
+ const parseMaintenanceEnv = (readEnv) => {
2217
+ const rawFoldBytes = readEnv("BAERLY_MAINTENANCE_MAX_FOLD_BYTES");
2218
+ let maxFoldBytes;
2219
+ if (rawFoldBytes !== void 0 && rawFoldBytes !== "") {
2220
+ const parsedFoldBytes = Number(rawFoldBytes);
2221
+ if (!/^[1-9][0-9]*$/.test(rawFoldBytes) || !Number.isSafeInteger(parsedFoldBytes)) throw new BaerlyError("InvalidConfig", `BAERLY_MAINTENANCE_MAX_FOLD_BYTES must be unset, "", or a positive decimal integer byte count no greater than ${Number.MAX_SAFE_INTEGER}, got ${JSON.stringify(rawFoldBytes)}`);
2222
+ maxFoldBytes = parsedFoldBytes;
2223
+ }
2224
+ const rawDisable = readEnv("BAERLY_MAINTENANCE_DISABLE");
2225
+ const normalizedDisable = rawDisable?.toLowerCase();
2226
+ let disabled;
2227
+ if (rawDisable === void 0 || normalizedDisable === "" || normalizedDisable === "0" || normalizedDisable === "false") disabled = false;
2228
+ else if (normalizedDisable === "1" || normalizedDisable === "true") disabled = true;
2229
+ else throw new BaerlyError("InvalidConfig", `BAERLY_MAINTENANCE_DISABLE must be one of "", "0", "false", "1", "true" (case-insensitive), got ${JSON.stringify(rawDisable)}`);
2230
+ return {
2231
+ ...maxFoldBytes !== void 0 && { maxFoldBytes },
2232
+ disabled
2233
+ };
2234
+ };
2235
+ export { logObjectKey as S, loadSnapshotAsMap as _, runScheduledMaintenance as a, isCallerFacing as b, rowBytes as c, isStorageRefusal as d, probeReadTail as f, walkLogRange as g, foldLogEntriesOnto as h, resolveFoldCeilings as i, findLogTail as l, probeTailFrom as m, isFoldViable as n, shouldFireMaintenance as o, probeTailChunk as p, parseMaintenanceEnv as r, projectSnapshot as s, dispatchWriteTick as t, forwardProbeCap as u, isOwnCollection as v, markCallerFacing as x, callerFacingCheck as y };
2236
+
2237
+ //# sourceMappingURL=maintenance-DevB6z4e.js.map