@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
@@ -1,7 +1,220 @@
1
- import { p as Storage, t as MetricsRecorder } from "./index-BYk9oCNf.js";
2
- import { o as MaintenanceDispatch } from "./maintenance-B_e0T99L.js";
3
-
4
- //#region packages/server/src/observability/recorder.d.ts
1
+ import { t as Storage } from "./types-suVbsEWS.js";
2
+ /**
3
+ * A request pool on a {@link RequestLedger}. `internal` is charged for
4
+ * every storage call. `external` is charged as well for a call that
5
+ * leaves through `fetch` (S3 over HTTP, GCS). The legacy cache-accounting
6
+ * seam also charges both pools; the production Worker never calls it.
7
+ * Charging an external call to both pools is safe whether
8
+ * the host keeps one combined counter or two separate ones.
9
+ */
10
+ type RequestPool = "internal" | "external";
11
+ /**
12
+ * Capacity a caller holds on a {@link RequestLedger} for calls it is about
13
+ * to issue (from {@link RequestLedger.hold}). Calls made with the hold
14
+ * active (passed to {@link RequestLedger.acquire}; `retryStorageCall` passes
15
+ * {@link currentRequestHold}) draw on it first; every other call in the
16
+ * invocation sees the ledger's room net of it, so concurrent work cannot
17
+ * spend it. Release it once the holder's calls are done; the unspent part
18
+ * returns to the ledger.
19
+ */
20
+ declare class RequestHold {
21
+ #private;
22
+ /** @internal Created by {@link RequestLedger.hold}. */
23
+ constructor(ledger: RequestLedger, amount: number);
24
+ /** Held requests not yet spent. */
25
+ get left(): number;
26
+ /** @internal `true` when this hold is on `ledger` and has room left. */
27
+ covers(ledger: RequestLedger): boolean;
28
+ /** @internal Spend one held request. */
29
+ spend(): void;
30
+ /** Return the unspent part to the ledger. Idempotent. */
31
+ release(): void;
32
+ }
33
+ /** Per-pool request limits. `Infinity` counts without ever refusing. */
34
+ interface RequestLedgerLimits {
35
+ readonly internal: number;
36
+ readonly external: number;
37
+ }
38
+ /** Requests charged so far, per pool, plus Cache API calls (also in `external`). */
39
+ interface RequestLedgerCharges {
40
+ readonly internal: number;
41
+ readonly external: number;
42
+ readonly cache: number;
43
+ }
44
+ /**
45
+ * Per-invocation storage request budget. The adapter creates one per
46
+ * invocation (an HTTP request, a cron tick) and the server carries it on
47
+ * the observability context, so everything that invocation runs,
48
+ * `ctx.waitUntil` work included, charges the same ledger.
49
+ *
50
+ * `retryStorageCall` charges one request before every attempt, so adapter
51
+ * retries and `list` pages are charged as they are issued. A request that
52
+ * does not fit is refused before it is sent: {@link acquire} throws
53
+ * `CapacityExceeded` whose cause carries `refused: true`, which ends the
54
+ * retry loop at once and keeps `notApplied` on a create. Charging is
55
+ * synchronous, so a `Promise.all` fan-out can never issue past the limit.
56
+ *
57
+ * Calls outside `retryStorageCall` (the verifier's JWKS fetch, GCS
58
+ * signing, app code in the same Worker) are not charged; the limits keep
59
+ * a margin below the platform cap for them.
60
+ */
61
+ declare class RequestLedger {
62
+ #private;
63
+ readonly limits: RequestLedgerLimits;
64
+ constructor(limits?: RequestLedgerLimits);
65
+ /** Requests charged so far. */
66
+ get charged(): RequestLedgerCharges;
67
+ /**
68
+ * Requests still allowed on `pool` to a caller without a hold: the room
69
+ * left, net of active holds. An external request also needs room in
70
+ * `internal`.
71
+ */
72
+ remaining(pool: RequestPool): number;
73
+ /** Requests held by active holds, not yet spent. */
74
+ get held(): number;
75
+ /**
76
+ * Hold `amount` requests for the caller's next calls; see
77
+ * {@link RequestHold}. The caller checks {@link storageRemaining} first:
78
+ * a hold never refuses, and one larger than the room left only blocks
79
+ * other callers sooner.
80
+ */
81
+ hold(amount: number): RequestHold;
82
+ /** @internal Return `amount` unspent held requests (`RequestHold.release`). */
83
+ unhold(amount: number): void;
84
+ /**
85
+ * Requests still allowed, net of active holds, on the pool this
86
+ * invocation's storage calls draw on: `external` once any storage call charged it, else `internal`
87
+ * once one charged that, else `Infinity` (no storage call has been
88
+ * charged, so the storage in use does not charge this ledger). A caller
89
+ * that must keep room for its next calls, such as the writer's
90
+ * commit-resolution reserve, checks this after its first storage call.
91
+ * Cache API calls do not count as storage calls here.
92
+ */
93
+ storageRemaining(): number;
94
+ /**
95
+ * Charge one request to `pool`, or refuse it before it is sent. With an
96
+ * active `hold` on this ledger the request draws on it (it needs only
97
+ * room left in `pool`); otherwise it needs room net of active holds.
98
+ *
99
+ * @throws BaerlyError code="CapacityExceeded", cause `{ refused: true }`,
100
+ * when `pool` has no room. Nothing is charged.
101
+ */
102
+ acquire(pool: RequestPool, hold?: RequestHold): void;
103
+ /**
104
+ * Legacy internal accounting seam; no production Worker caller.
105
+ * Charge one optional Cache API call when it fits: room in `external`
106
+ * and fewer than {@link CF_CACHE_API_MAX_CALLS} cache calls so far.
107
+ * Returns `false`, charging nothing, when it does not; the caller skips
108
+ * the cache call. With `required`, the call is charged whether or not
109
+ * it fits and always returns `true`. Tests use this to model an
110
+ * unrefusable call consuming the platform margin.
111
+ */
112
+ chargeCacheCall(required?: boolean): boolean;
113
+ }
114
+ /**
115
+ * `MetricsRecorder` — internal emission contract for the load-bearing
116
+ * kernel metrics. Writer / compactor / GC emit through
117
+ * an instance of this interface; in production the instance is the
118
+ * per-request `RequestScopedMetricsRecorder` on the active
119
+ * `ObservabilityContext`, and emissions flow onto the canonical line
120
+ * via `summarize()`. Tests use a local `InMemoryMetricsRecorder` and
121
+ * wrap their workload in `runWithContext` to attach it.
122
+ *
123
+ * Operators do not wire a custom sink against this interface — the
124
+ * operator's view of kernel emissions is the canonical line on
125
+ * stdout (one JSON object per HTTP request).
126
+ *
127
+ * **Naming convention** matches the load-bearing metrics:
128
+ * - `db.write.class_a_ops_per_logical_write` — histogram (recommend p99 alert ~5; not gated).
129
+ * The committing log create, 1 per commit. Idle-reader cost is unchanged.
130
+ * - `db.r2.put.412_total` — counter (CAS conflict / If-Match-or-None-Match loss)
131
+ * - `db.r2.put.429_total` — counter (R2 prefix-partition rate-limit)
132
+ * - `db.write.ambiguous_commit_total` — counter, labelled by `collection`
133
+ * and `cleanup` (`deleted` / `failed`). A committing create won at a
134
+ * sequence already certified deleted, so the commit failed with
135
+ * `AmbiguousCommit` rather than acknowledging a mutation whose
136
+ * visibility cannot be determined.
137
+ * `cleanup` reports whether the phantom log object was reclaimed. Any
138
+ * sustained rate means writers are pausing across a fold plus a
139
+ * retirement pass; a `failed` rate leaves behind sub-floor objects that
140
+ * leak permanently — they sit below `log_delete_floor`, where
141
+ * computed-range retirement starts, so nothing revisits them
142
+ * - `db.write.delete_floor_check_skipped_total` — counter, labelled by
143
+ * `collection`. The post-create re-read of `current.json` inside
144
+ * `Writer#assertCommitAboveDeleteFloor` failed with a non-abort error, so
145
+ * the delete-floor check was skipped for that commit rather than
146
+ * evaluated. A sustained rate means the check is not covering the writes
147
+ * it exists to protect, even though no individual commit is rejected.
148
+ * - `db.write.post_commit_refused_total` — counter, labelled by
149
+ * `collection` and `phase` (`delete-floor-check`, the only post-commit
150
+ * step). The request ledger refused a storage call of a step that runs
151
+ * after a known commit; the step was skipped and the commit stands. The
152
+ * floor check runs inside the commit's ledger hold, so a count means a call outside every hold, or a
153
+ * platform cap below the ledger's limit, cut into it.
154
+ * - `db.write.unresolved_create_total` — counter, labelled by
155
+ * `collection`. A rejected committing create could not be resolved by
156
+ * readback, so the commit failed with `AmbiguousCommit`.
157
+ * - `db.write.maintenance_dispatch_failed_total` — counter, labelled by
158
+ * `collection`. The maintenance dispatcher threw or rejected after a
159
+ * durable commit, so that write's maintenance tick did not run.
160
+ * - `db.write.insert_replayed_total` — counter, labelled by `collection`.
161
+ * An SDK-minted insert (`mintedId`) found its identical row already
162
+ * stored and returned it as the original success, committing nothing.
163
+ * A rate tracks clients retransmitting inserts after lost responses.
164
+ * - `db.read.decoded_entries_total` / `db.read.live_documents_total` /
165
+ * `db.read.returned_rows_total` — counters, labelled by `collection`,
166
+ * emitted together by every collection read (a read terminal, or a
167
+ * write verb's pre-commit read). Units:
168
+ * - decoded entries: snapshot rows plus log entries the fold decoded,
169
+ * before predicate and limit. Entries, not documents: an `_id`
170
+ * updated twice since the last fold counts three times, and a
171
+ * deleted row still counts its `I` and its `D`.
172
+ * - live documents: distinct documents live once the fold completes,
173
+ * before predicate, order and limit.
174
+ * - returned rows: rows left after predicate, order and limit — the
175
+ * rows a read returns, the rows `count()` counts, or the rows a write
176
+ * verb's read matched.
177
+ * A never-provisioned collection reports zeros. A point read still
178
+ * folds the whole collection, so a large decoded count beside one
179
+ * returned row is that read's actual work. No threshold or cap attaches.
180
+ * - `db.manifest.lag_window_depth` — gauge (alert at >100)
181
+ * - `db.gc.entries_swept_per_second` — gauge (livelock indicator when <writes/s)
182
+ * - `db.orphan.candidate_count` — gauge (`gc/pending.json` depth)
183
+ * - `db.compact.entries_folded` — histogram (entries folded per run)
184
+ * - `db.compaction.deferred_total` — counter, labelled by `collection`,
185
+ * `dimension` (`bytes` / `rows`) and `gate` (`pre-fold` / `rebuild`).
186
+ * The write-tick fold hit the snapshot ceiling (`C` / `E`) and did not
187
+ * run: `log_seq_start` and log retention are frozen until it folds again.
188
+ * Emitted once per deferral by the write-tick runner, never by compact().
189
+ * - `db.compaction.deferred_bytes_total` / `db.compaction.deferred_rows_total`
190
+ * — the same event under a per-dimension name, labelled by `collection`
191
+ * and `gate`, because the canonical line keys counters by name and drops
192
+ * labels
193
+ * - `db.gc.swept_total` — counter (labelled by reason)
194
+ * - `db.gc.dropped_total` — counter (labelled by cause: `stale-generation`
195
+ * / `still-live`). Candidates resolved out of the ledger WITHOUT a
196
+ * DELETE because the sweep gate re-checked them and found them no
197
+ * longer eligible. A drop frees no bytes, so this is deliberately
198
+ * not folded into `db.gc.swept_total` — a pass that reclaimed
199
+ * nothing must not read as productive. One `stale-generation` spike
200
+ * per restore or upgrade is expected; a sustained `still-live` rate
201
+ * means the mark phase is misjudging liveness
202
+ *
203
+ * Names follow `db.<subsystem>.<metric>`, dot-separated, all-lowercase
204
+ * snake_case segments. Labels are flat
205
+ * `Readonly<Record<string, string>>` — no numbers, no nested objects.
206
+ *
207
+ * Metric emissions never throw on the hot path; the default
208
+ * `noopMetricsRecorder` cannot throw.
209
+ */
210
+ interface MetricsRecorder {
211
+ /** Monotonically-incrementing event count. */
212
+ counter(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
213
+ /** Point-in-time value. */
214
+ gauge(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
215
+ /** Distribution sample. */
216
+ histogram(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
217
+ }
5
218
  /** One observation row, kept in insertion order. */
6
219
  interface ObservationRow {
7
220
  readonly name: string;
@@ -58,8 +271,6 @@ declare class RequestScopedMetricsRecorder implements MetricsRecorder {
58
271
  */
59
272
  summarize(): MetricsSummary;
60
273
  }
61
- //#endregion
62
- //#region packages/server/src/observability/context.d.ts
63
274
  /** Read-mostly per-request observability state. */
64
275
  interface ObservabilityContext {
65
276
  /** Externally-correlatable request identifier (UUID-ish). */
@@ -81,14 +292,20 @@ interface ObservabilityContext {
81
292
  */
82
293
  readonly recorder: RequestScopedMetricsRecorder;
83
294
  /**
84
- * Per-request write-tick maintenance dispatch config. Set by the
85
- * adapter (NOT `Db.create`) so the inherently-per-request
86
- * `dispatch = ctx.waitUntil` and the env-var-derived caps ride the
87
- * same scope the kernel write-tick reads from. The {@link Writer}
88
- * consults `getCurrentContext()?.maintenance` at the post-commit
89
- * dispatch point. Absent ⇒ inline dispatch + CF-free-safe caps.
295
+ * The invocation's storage request budget. Set by the adapter that owns
296
+ * the invocation (an HTTP request, a Workers cron tick) with its host's
297
+ * limits. Every storage attempt run inside this context, `waitUntil`
298
+ * work included, is charged to it by `retryStorageCall`, and one that
299
+ * does not fit is refused before it is sent. Absent ⇒ nothing is charged.
90
300
  */
91
- readonly maintenance?: MaintenanceDispatch;
301
+ readonly ledger?: RequestLedger;
302
+ /**
303
+ * A hold on `ledger` that storage calls in this context draw on first.
304
+ * Set only by the writer, on a child context scoped to one commit slot's
305
+ * calls (`Writer#withCommitHold`); work dispatched from outside that
306
+ * scope never sees it.
307
+ */
308
+ readonly hold?: RequestHold;
92
309
  }
93
310
  /**
94
311
  * Optional construction inputs. All fields are optional so callers in
@@ -106,16 +323,9 @@ interface ObservabilityContext {
106
323
  interface ObservabilityContextInit {
107
324
  readonly request_id?: string;
108
325
  readonly recorder?: RequestScopedMetricsRecorder;
109
- /** Write-tick maintenance dispatch config. See {@link ObservabilityContext.maintenance}. */
110
- readonly maintenance?: MaintenanceDispatch;
326
+ /** Storage request budget. See {@link ObservabilityContext.ledger}. */
327
+ readonly ledger?: RequestLedger;
111
328
  }
112
- /**
113
- * Factory for {@link ObservabilityContext}. We use a factory rather
114
- * than a class so consumers can structural-type the result and so
115
- * the `AsyncLocalStorage` slot type stays a plain interface — no
116
- * surprises around `instanceof` across realms (Workers vs Node).
117
- */
118
- declare const createObservabilityContext: (init?: ObservabilityContextInit) => ObservabilityContext;
119
329
  /**
120
330
  * Run `fn` with `ctx` active as the current observability context.
121
331
  * Inside `fn` (and any `await`-chained continuation rooted in `fn`),
@@ -130,24 +340,12 @@ declare const createObservabilityContext: (init?: ObservabilityContextInit) => O
130
340
  * indirection.
131
341
  */
132
342
  declare const runWithContext: <T>(ctx: ObservabilityContext, fn: () => T | Promise<T>) => T | Promise<T>;
133
- /** Returns the currently-active context, or `undefined` outside one. */
134
- declare const getCurrentContext: () => ObservabilityContext | undefined;
135
- //#endregion
136
- //#region node_modules/.pnpm/@logtape+logtape@2.2.2/node_modules/@logtape/logtape/dist/level.d.ts
137
343
  //#region src/level.d.ts
138
344
  declare const logLevels: readonly ["trace", "debug", "info", "warning", "error", "fatal"];
139
345
  /**
140
346
  * The severity level of a {@link LogRecord}.
141
347
  */
142
348
  type LogLevel = typeof logLevels[number];
143
- /**
144
- * Lists all available log levels with the order of their severity.
145
- * The `"trace"` level goes first, and the `"fatal"` level goes last.
146
- * @returns A new copy of the array of log levels.
147
- * @since 1.0.0
148
- */
149
- //#endregion
150
- //#region node_modules/.pnpm/@logtape+logtape@2.2.2/node_modules/@logtape/logtape/dist/record.d.ts
151
349
  //#region src/record.d.ts
152
350
  /**
153
351
  * A log record.
@@ -190,10 +388,46 @@ interface LogRecord {
190
388
  * The extra properties of the log record.
191
389
  */
192
390
  readonly properties: Record<string, unknown>;
193
- } //# sourceMappingURL=record.d.ts.map
194
- //#endregion
195
- //#endregion
196
- //#region node_modules/.pnpm/@logtape+logtape@2.2.2/node_modules/@logtape/logtape/dist/sink.d.ts
391
+ /**
392
+ * Where in the source code the logging method that made this log record
393
+ * was called.
394
+ *
395
+ * It is present only if source location capture is enabled for the logger
396
+ * (see `LoggerConfig.captureSourceLocation`) and the runtime's stack
397
+ * trace could be parsed; otherwise the property is absent.
398
+ *
399
+ * @since 2.4.0
400
+ */
401
+ readonly sourceLocation?: SourceLocation;
402
+ }
403
+ /**
404
+ * A location in the source code, as reported by the JavaScript runtime's
405
+ * stack trace.
406
+ *
407
+ * The position is the one of the code that actually runs. LogTape does not
408
+ * resolve source maps, so bundled or minified code may report positions in
409
+ * the generated code, unless the runtime itself applies source maps to
410
+ * stack traces.
411
+ *
412
+ * @since 2.4.0
413
+ */
414
+ interface SourceLocation {
415
+ /**
416
+ * The file path or URL exactly as the runtime reported it, e.g.,
417
+ * `"file:///app/src/main.ts"`, `"/app/src/main.ts"`, or
418
+ * `"http://localhost:5173/src/main.ts?t=1700000000000"`.
419
+ */
420
+ readonly file: string;
421
+ /**
422
+ * The 1-based line number.
423
+ */
424
+ readonly line: number;
425
+ /**
426
+ * The 1-based column number. Runtimes differ in which part of the call
427
+ * expression it points to.
428
+ */
429
+ readonly column: number;
430
+ }
197
431
  //#region src/sink.d.ts
198
432
  /**
199
433
  * A sink is a function that accepts a log record and prints it somewhere.
@@ -205,17 +439,6 @@ interface LogRecord {
205
439
  * @param record The log record to sink.
206
440
  */
207
441
  type Sink = (record: LogRecord) => void;
208
- /**
209
- * An async sink is a function that accepts a log record and asynchronously
210
- * processes it. This type is used with {@link fromAsyncSink} to create
211
- * a regular sink that properly handles asynchronous operations.
212
- *
213
- * @param record The log record to process asynchronously.
214
- * @returns A promise that resolves when the record has been processed.
215
- * @since 1.0.0
216
- */
217
- //#endregion
218
- //#region node_modules/.pnpm/@logtape+logtape@2.2.2/node_modules/@logtape/logtape/dist/logger.d.ts
219
442
  /**
220
443
  * A logger interface. It provides methods to log messages at different
221
444
  * severity levels.
@@ -1292,12 +1515,6 @@ type LogCallback = (prefix: LogTemplatePrefix) => unknown[];
1292
1515
  * @returns The rendered message array.
1293
1516
  */
1294
1517
  type LogTemplatePrefix = (message: TemplateStringsArray, ...values: unknown[]) => unknown[];
1295
- /**
1296
- * A function type for logging methods in the {@link Logger} interface.
1297
- * @since 1.0.0
1298
- */
1299
- //#endregion
1300
- //#region packages/server/src/observability/logger.d.ts
1301
1518
  /**
1302
1519
  * Canonical category names. Use these instead of bare strings.
1303
1520
  *
@@ -1310,6 +1527,8 @@ type LogTemplatePrefix = (message: TemplateStringsArray, ...values: unknown[]) =
1310
1527
  */
1311
1528
  declare const CATEGORY: {
1312
1529
  readonly http: readonly ["baerly", "http"];
1530
+ /** Write-tick maintenance events, routed via `MaintenanceDispatch.warn`. */
1531
+ readonly maintenance: readonly ["baerly", "maintenance"];
1313
1532
  readonly storage: readonly ["baerly", "storage"];
1314
1533
  };
1315
1534
  /** Logical type of a `CATEGORY.*` value. */
@@ -1336,7 +1555,7 @@ interface ObservabilityConfig {
1336
1555
  * targeting TTY environments (e.g. `@baerly/adapter-node`'s
1337
1556
  * `baerlyDev()` Vite-mount path) construct a pretty sink locally
1338
1557
  * and pass it as a function; the kernel deliberately does not
1339
- * ship a pretty-printer to keep `picocolors` off the runtime
1558
+ * ship a pretty-printer to keep the pretty renderer off the runtime
1340
1559
  * closure.
1341
1560
  *
1342
1561
  * Default: `"console-json"`.
@@ -1359,8 +1578,6 @@ declare const configureObservability: (config?: ObservabilityConfig) => Promise<
1359
1578
  * strings still work for ad-hoc instrumentation.
1360
1579
  */
1361
1580
  declare const getLogger: (category: string | readonly string[]) => Logger;
1362
- //#endregion
1363
- //#region packages/server/src/observability/canonical.d.ts
1364
1581
  /** Options accepted by {@link flushCanonicalLine}. */
1365
1582
  interface FlushCanonicalLineOptions {
1366
1583
  readonly unit: "http";
@@ -1369,7 +1586,7 @@ interface FlushCanonicalLineOptions {
1369
1586
  /**
1370
1587
  * Short outcome tag. In production all callsites route through
1371
1588
  * {@link deriveOutcome} which yields one of `"read"` /
1372
- * `"committed"` / `"conflict"` / `"error"`; the field is typed
1589
+ * `"committed"` / `"conflict"` / `"refused"` / `"error"`; the field is typed
1373
1590
  * `string` so test fixtures and future units can pass a
1374
1591
  * unit-specific tag without type gymnastics.
1375
1592
  */
@@ -1389,7 +1606,7 @@ interface FlushCanonicalLineOptions {
1389
1606
  declare const flushCanonicalLine: (ctx: ObservabilityContext, recorder: RequestScopedMetricsRecorder, opts: FlushCanonicalLineOptions) => void;
1390
1607
  /**
1391
1608
  * HTTP unit-of-work scope. Opens an {@link ObservabilityContext} from the
1392
- * inbound `Request` (request id from `x-request-id` header or generated),
1609
+ * inbound `Request` (request id from a valid `x-request-id` header or generated),
1393
1610
  * runs `fetch(req)` under {@link runWithContext}, and flushes the canonical
1394
1611
  * line in finally with `unit: "http"`.
1395
1612
  *
@@ -1408,18 +1625,6 @@ declare const flushCanonicalLine: (ctx: ObservabilityContext, recorder: RequestS
1408
1625
  * have under the in-Hono middleware.
1409
1626
  */
1410
1627
  declare const withHttpObservability: (req: Request, fetch: (req: Request) => Promise<Response> | Response) => Promise<Response>;
1411
- /**
1412
- * Verifier rejected the request — log the warn, flush the canonical
1413
- * line, and return the 401 envelope Response. Adapters call this
1414
- * inside `runWithContext(obsCtx, ...)` so the canonical line lands on
1415
- * the same context the rest of the request would have used.
1416
- *
1417
- * Both adapters share this so the 401 wire shape AND the
1418
- * observability record are byte-identical across runtimes.
1419
- */
1420
- declare const flushUnauthorizedAndRespond: (obsCtx: ObservabilityContext, req: Request) => Response;
1421
- //#endregion
1422
- //#region packages/server/src/observability/storage.d.ts
1423
1628
  /**
1424
1629
  * Wrap `inner` with metric emission. The returned object is itself
1425
1630
  * a `Storage` impl and passes the `Storage` conformance suite
@@ -1431,8 +1636,6 @@ declare const flushUnauthorizedAndRespond: (obsCtx: ObservabilityContext, req: R
1431
1636
  * outside any context they fall through to {@link noopMetricsRecorder}.
1432
1637
  */
1433
1638
  declare const observableStorage: (inner: Storage) => Storage;
1434
- //#endregion
1435
- //#region packages/server/src/observability/derive-outcome.d.ts
1436
1639
  /**
1437
1640
  * Canonical-line outcome derivation for HTTP requests. Shared
1438
1641
  * helper used by `packages/server/src/http/router.ts` (Mode B
@@ -1442,6 +1645,10 @@ declare const observableStorage: (inner: Storage) => Storage;
1442
1645
  *
1443
1646
  * Classification rules (evaluated in order):
1444
1647
  *
1648
+ * 0. `error.code` is `CapacityExceeded` (409) or `MaintenancePending`
1649
+ * (503) → `"refused"`: the capacity check refused the write before
1650
+ * any commit. Neither is a server fault nor a write conflict, so
1651
+ * they stay out of the `"error"` and `"conflict"` rates.
1445
1652
  * 1. `error !== undefined && status >= 500` → `"error"`. The
1446
1653
  * handler threw and the wire status surfaced as 5xx; the
1447
1654
  * canonical line carries the diagnostic at error level.
@@ -1464,8 +1671,14 @@ declare const observableStorage: (inner: Storage) => Storage;
1464
1671
  * any). Optional — pass `undefined` on the
1465
1672
  * happy path.
1466
1673
  */
1467
- type Outcome = "read" | "committed" | "conflict" | "error";
1674
+ type Outcome = "read" | "committed" | "conflict" | "refused" | "error";
1468
1675
  declare const deriveOutcome: (method: string, status: number, error?: unknown) => Outcome;
1469
- //#endregion
1470
- export { ObservabilityContextInit as _, flushCanonicalLine as a, runWithContext as b, CATEGORY as c, ObservabilityConfig as d, configureObservability as f, ObservabilityContext as g, LogRecord as h, FlushCanonicalLineOptions as i, CategoryName as l, Sink as m, deriveOutcome as n, flushUnauthorizedAndRespond as o, getLogger as p, observableStorage as r, withHttpObservability as s, Outcome as t, FriendlyLogLevel as u, createObservabilityContext as v, getCurrentContext as y };
1471
- //# sourceMappingURL=index-CuA9Mi3K.d.ts.map
1676
+ /**
1677
+ * Build a per-unit-of-work {@link ObservabilityContext}. Pass it to
1678
+ * {@link runWithContext}; every kernel emission inside reaches its
1679
+ * recorder.
1680
+ */
1681
+ declare const createObservabilityContext: (init?: ObservabilityContextInit) => ObservabilityContext;
1682
+ /** Returns the currently-active context, or `undefined` outside one. */
1683
+ declare const getCurrentContext: () => ObservabilityContext | undefined;
1684
+ export { ObservabilityContext as _, observableStorage as a, MetricsRecorder as b, withHttpObservability as c, FriendlyLogLevel as d, ObservabilityConfig as f, LogRecord as g, Sink as h, deriveOutcome as i, CATEGORY as l, getLogger as m, getCurrentContext as n, FlushCanonicalLineOptions as o, configureObservability as p, Outcome as r, flushCanonicalLine as s, createObservabilityContext as t, CategoryName as u, ObservabilityContextInit as v, runWithContext as y };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,27 @@
1
- import { a as CollectionNames, c as defineConfig, d as IndexDefinition, f as DocumentData, i as CollectionDefinition, l as SchemaIssue, n as BaerlyAppConfig, o as RowOf, r as BaerlyConfig, s as UnboundConfig, u as SchemaValidator } from "./app-config-DyiFK3_k.js";
2
- import { a as MemoryStorage, b as BaerlyErrorCode, c as Predicate, g as StorageListEntry, h as StorageGetResult, i as VerifierResult, l as Query, o as Collection, p as Storage, r as Verifier, u as PredicateArg, v as StoragePutResult, y as BaerlyError } from "./index-BYk9oCNf.js";
3
- import { t as allIndexKeysFor } from "./indexes-Dn9hbGQG.js";
4
- import { a as loadSnapshotAsMap, c as collectionsToMaps, i as encodeSnapshotBody, n as walkLogRange, o as snapshotKey, r as SnapshotBody, s as resolveVerifier, t as probeTailFrom } from "./index-BNRh23K9.js";
5
- import { n as validateOrThrow, t as Db } from "./db-DsPkOVEH.js";
6
- export { type BaerlyAppConfig, type BaerlyConfig, BaerlyError, type BaerlyErrorCode, type Collection, type CollectionDefinition, type CollectionNames, Db, type DocumentData, type IndexDefinition, MemoryStorage, type Predicate, type PredicateArg, type Query, type RowOf, type SchemaIssue, type SchemaValidator, type SnapshotBody, type Storage, type StorageGetResult, type StorageListEntry, type StoragePutResult, type UnboundConfig, type Verifier, type VerifierResult, allIndexKeysFor, collectionsToMaps, defineConfig, encodeSnapshotBody, loadSnapshotAsMap, probeTailFrom, resolveVerifier, snapshotKey, validateOrThrow, walkLogRange };
1
+ /**
2
+ * Public barrel for `baerly-storage`. The canonical top-level
3
+ * surface — read/write API, config types, storage adapter
4
+ * contracts, and the curated protocol-kernel re-exports.
5
+ *
6
+ * Subpaths carry the rest of the surface:
7
+ *
8
+ * - `@gusto/baerly-storage/auth` — auth presets (`bearerJwt`,
9
+ * `cloudflareAccess`, `sharedSecret`).
10
+ * - `@gusto/baerly-storage/http` — `createRouter`, `mapError`,
11
+ * `listEventsSince`, `longPollSince`, body-size cap.
12
+ * - `@gusto/baerly-storage/maintenance` — `runScheduledMaintenance`,
13
+ * the opt-in scheduled pass.
14
+ * - `@gusto/baerly-storage/observability` — context, recorder,
15
+ * canonical-line helpers, logger config.
16
+ *
17
+ * Kernel internals the CLI, adapters, and bench share (snapshot codec,
18
+ * log walk, verifier resolution) live on the unpublished
19
+ * `@baerly/server/_internal/kernel` subpath.
20
+ */
21
+ import { a as CollectionNames, c as defineConfig, d as IndexDefinition, f as DocumentData, h as MergePatch, i as CollectionDefinition, l as SchemaIssue, n as BaerlyAppConfig, o as RowOf, r as BaerlyConfig, s as UnboundConfig, u as SchemaValidator } from "./app-config-C6qW7m8S.js";
22
+ import { a as PredicateArg, c as BaerlyErrorOptions, i as Query, o as BaerlyError, r as Predicate, s as BaerlyErrorCode, t as Collection } from "./collection-api-DbyhLAY8.js";
23
+ import { i as StorageListEntry, o as StoragePutResult, r as StorageGetResult, t as Storage } from "./types-suVbsEWS.js";
24
+ import { t as MemoryStorage } from "./index-LEgHN0qJ.js";
25
+ import { n as VerifierResult, t as Verifier } from "./verifier-Bmlmndzo.js";
26
+ import { t as Db } from "./db-plFUNTSF.js";
27
+ export { type BaerlyAppConfig, type BaerlyConfig, BaerlyError, type BaerlyErrorCode, type BaerlyErrorOptions, type Collection, type CollectionDefinition, type CollectionNames, Db, type DocumentData, type IndexDefinition, MemoryStorage, type MergePatch, type Predicate, type PredicateArg, type Query, type RowOf, type SchemaIssue, type SchemaValidator, type Storage, type StorageGetResult, type StorageListEntry, type StoragePutResult, type UnboundConfig, type Verifier, type VerifierResult, defineConfig };
package/dist/index.js CHANGED
@@ -1,6 +1,4 @@
1
1
  import { defineConfig } from "./app-config.js";
2
- import { t as BaerlyError } from "./errors-Dfa3p78c.js";
3
- import { b as loadSnapshotAsMap, g as allIndexKeysFor, h as walkLogRange, w as probeTailFrom, x as snapshotKey, y as encodeSnapshotBody } from "./maintenance-B4Dki6Ig.js";
4
- import { i as MemoryStorage, n as resolveVerifier, r as collectionsToMaps, t as Db } from "./src-CYHFDrKz.js";
5
- import { o as validateOrThrow } from "./query-rAtXNQQB.js";
6
- export { BaerlyError, Db, MemoryStorage, allIndexKeysFor, collectionsToMaps, defineConfig, encodeSnapshotBody, loadSnapshotAsMap, probeTailFrom, resolveVerifier, snapshotKey, validateOrThrow, walkLogRange };
2
+ import { t as BaerlyError } from "./errors-7Rk1HGCE.js";
3
+ import { n as MemoryStorage, t as Db } from "./src-Dr9uo3dc.js";
4
+ export { BaerlyError, Db, MemoryStorage, defineConfig };