@gusto/baerly-storage 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/README.md +157 -92
  2. package/dist/API.md +64 -32
  3. package/dist/CHANGELOG.md +295 -5
  4. package/dist/RECIPES.md +125 -0
  5. package/dist/THIRD-PARTY-LICENSES.txt +22 -96
  6. package/dist/{app-config-BIzyAKzy.d.ts → app-config-DyiFK3_k.d.ts} +43 -11
  7. package/dist/app-config.d.ts +1 -1
  8. package/dist/auth.d.ts +1 -1
  9. package/dist/auth.js +13 -13
  10. package/dist/auth.js.map +1 -1
  11. package/dist/aws4fetch.esm-p7eEzLCs.js +1702 -0
  12. package/dist/aws4fetch.esm-p7eEzLCs.js.map +1 -0
  13. package/dist/baerly.js +35 -15
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +342 -0
  16. package/dist/{client-BJXF3XJA.d.ts → client-Fe8CwB73.d.ts} +3 -3
  17. package/dist/client-react.d.ts +3 -3
  18. package/dist/client-react.js +4 -4
  19. package/dist/client-react.js.map +1 -1
  20. package/dist/client.d.ts +4 -4
  21. package/dist/client.js +3 -3
  22. package/dist/{cloudflare-Cn2ibODt.js → cloudflare-DzKBrUlg.js} +2 -2
  23. package/dist/{cloudflare-Cn2ibODt.js.map → cloudflare-DzKBrUlg.js.map} +1 -1
  24. package/dist/cloudflare.d.ts +49 -6
  25. package/dist/cloudflare.js +55 -21
  26. package/dist/cloudflare.js.map +1 -1
  27. package/dist/config-1tv0-Yzm.js +2693 -0
  28. package/dist/config-1tv0-Yzm.js.map +1 -0
  29. package/dist/constants-CfeMWQWk.js +222 -0
  30. package/dist/constants-CfeMWQWk.js.map +1 -0
  31. package/dist/{cost-BZ_MDBmn.js → cost-DSMIVqzL.js} +42 -43
  32. package/dist/cost-DSMIVqzL.js.map +1 -0
  33. package/dist/{current-json-DsN7FNY1.js → current-json-C6nhPOm1.js} +6 -204
  34. package/dist/current-json-C6nhPOm1.js.map +1 -0
  35. package/dist/{db-CCT6tDfY.d.ts → db-DsPkOVEH.d.ts} +3 -3
  36. package/dist/{deploy-BKKyGlSJ.js → deploy-DonTr-CV.js} +4 -4
  37. package/dist/{deploy-BKKyGlSJ.js.map → deploy-DonTr-CV.js.map} +1 -1
  38. package/dist/dev-vite.d.ts +9 -5
  39. package/dist/dev-vite.js +5 -4
  40. package/dist/dev-vite.js.map +1 -1
  41. package/dist/dev.d.ts +1 -1
  42. package/dist/dev.js +1 -1
  43. package/dist/{doctor-BVU4GNXN.js → doctor-DSIyCDg_.js} +5 -8
  44. package/dist/{doctor-BVU4GNXN.js.map → doctor-DSIyCDg_.js.map} +1 -1
  45. package/dist/{dump-DPEAKub6.js → dump-Bh5k26VQ.js} +9 -32
  46. package/dist/dump-Bh5k26VQ.js.map +1 -0
  47. package/dist/{errors-DOdL95kK.js → errors-Dfa3p78c.js} +25 -5
  48. package/dist/errors-Dfa3p78c.js.map +1 -0
  49. package/dist/{export-BcuCLFFe.js → export-DtF5tDIM.js} +9 -32
  50. package/dist/{export-BcuCLFFe.js.map → export-DtF5tDIM.js.map} +1 -1
  51. package/dist/{fsck-RXgLOaJG.js → fsck-D_djMO5D.js} +10 -33
  52. package/dist/fsck-D_djMO5D.js.map +1 -0
  53. package/dist/{http-Bd4byR4n.js → http-DxM9MflO.js} +123 -35
  54. package/dist/http-DxM9MflO.js.map +1 -0
  55. package/dist/http.d.ts +42 -26
  56. package/dist/http.js +3 -2
  57. package/dist/{index-DnBGSeuU.d.ts → index-0rZcMBwy.d.ts} +2 -2
  58. package/dist/{index-Cmsxx-ZN.d.ts → index-B6oexfOB.d.ts} +7 -7
  59. package/dist/{index-BDceQQi-.d.ts → index-BNRh23K9.d.ts} +4 -4
  60. package/dist/{index-DW7GT6M2.d.ts → index-BYk9oCNf.d.ts} +193 -163
  61. package/dist/index.d.ts +6 -6
  62. package/dist/index.js +4 -4
  63. package/dist/{indexes-Cx7uMXm0.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
  64. package/dist/{inspect-DhI49PSi.js → inspect-6WZ-pC7-.js} +10 -33
  65. package/dist/inspect-6WZ-pC7-.js.map +1 -0
  66. package/dist/key-Di6yyxFu.js +35 -0
  67. package/dist/key-Di6yyxFu.js.map +1 -0
  68. package/dist/{log-tail-DXeDkWEp.js → log-tail-D98U1JBo.js} +31 -7
  69. package/dist/log-tail-D98U1JBo.js.map +1 -0
  70. package/dist/{maintenance-CWBQpZ2y.js → maintenance-B4Dki6Ig.js} +77 -22
  71. package/dist/maintenance-B4Dki6Ig.js.map +1 -0
  72. package/dist/{maintenance-BkhUr72A.d.ts → maintenance-B_e0T99L.d.ts} +28 -5
  73. package/dist/{maintenance-C_KSkVjd.js → maintenance-C7coQp4c.js} +17 -16
  74. package/dist/maintenance-C7coQp4c.js.map +1 -0
  75. package/dist/maintenance.d.ts +3 -3
  76. package/dist/maintenance.js +3 -3
  77. package/dist/node.d.ts +168 -65
  78. package/dist/node.js +3 -2
  79. package/dist/{normalize-XWY25_sG.js → normalize-rjnZLwS4.js} +2 -2
  80. package/dist/normalize-rjnZLwS4.js.map +1 -0
  81. package/dist/{observability-BYd-RzEx.js → observability-wzs3-BL_.js} +233 -71
  82. package/dist/observability-wzs3-BL_.js.map +1 -0
  83. package/dist/observability.d.ts +2 -2
  84. package/dist/observability.js +1 -1
  85. package/dist/{plan-DIu_B6fy.js → plan-a7PJHBCy.js} +2 -2
  86. package/dist/{plan-DIu_B6fy.js.map → plan-a7PJHBCy.js.map} +1 -1
  87. package/dist/{query-sQNO5vU_.js → query-rAtXNQQB.js} +96 -207
  88. package/dist/query-rAtXNQQB.js.map +1 -0
  89. package/dist/{rebuild-index-DP4CqSSs.js → rebuild-index-BVzQSZlm.js} +9 -32
  90. package/dist/rebuild-index-BVzQSZlm.js.map +1 -0
  91. package/dist/{request-BEF_OvMh.js → request-u0M51mhJ.js} +3 -3
  92. package/dist/{request-BEF_OvMh.js.map → request-u0M51mhJ.js.map} +1 -1
  93. package/dist/{restore-DpQYef6r.js → restore-R-4rbciV.js} +73 -100
  94. package/dist/restore-R-4rbciV.js.map +1 -0
  95. package/dist/runtime-spec-qL3_lTTU.js +391 -0
  96. package/dist/runtime-spec-qL3_lTTU.js.map +1 -0
  97. package/dist/s3-http-B-z8th6O.d.ts +60 -0
  98. package/dist/s3.d.ts +47 -0
  99. package/dist/s3.js +45 -0
  100. package/dist/s3.js.map +1 -0
  101. package/dist/{shared-secret-BJdSwpgw.js → shared-secret-DgEicd3x.js} +13 -5
  102. package/dist/shared-secret-DgEicd3x.js.map +1 -0
  103. package/dist/src-BG20LZs7.js +2271 -0
  104. package/dist/src-BG20LZs7.js.map +1 -0
  105. package/dist/{src-Db4-qVtM.js → src-CYHFDrKz.js} +51 -8
  106. package/dist/src-CYHFDrKz.js.map +1 -0
  107. package/dist/{src-CWpkSbvJ.js → src-DYZ4H1aF.js} +6 -5
  108. package/dist/src-DYZ4H1aF.js.map +1 -0
  109. package/dist/{subcommand-CP9NY2J4.js → subcommand-DoDA-K7d.js} +44 -6
  110. package/dist/subcommand-DoDA-K7d.js.map +1 -0
  111. package/dist/time-DUqvFMHq.js +119 -0
  112. package/dist/time-DUqvFMHq.js.map +1 -0
  113. package/dist/{usage-CTfDq9HR.js → usage-DBV1eQHC.js} +7 -22
  114. package/dist/usage-DBV1eQHC.js.map +1 -0
  115. package/dist/wire-izfGZDvr.js.map +1 -1
  116. package/package.json +52 -28
  117. package/dist/config-CGyBopy3.js +0 -5326
  118. package/dist/config-CGyBopy3.js.map +0 -1
  119. package/dist/cost-BZ_MDBmn.js.map +0 -1
  120. package/dist/current-json-DsN7FNY1.js.map +0 -1
  121. package/dist/dump-DPEAKub6.js.map +0 -1
  122. package/dist/errors-DOdL95kK.js.map +0 -1
  123. package/dist/fsck-RXgLOaJG.js.map +0 -1
  124. package/dist/http-Bd4byR4n.js.map +0 -1
  125. package/dist/inspect-DhI49PSi.js.map +0 -1
  126. package/dist/log-tail-DXeDkWEp.js.map +0 -1
  127. package/dist/maintenance-CWBQpZ2y.js.map +0 -1
  128. package/dist/maintenance-C_KSkVjd.js.map +0 -1
  129. package/dist/normalize-XWY25_sG.js.map +0 -1
  130. package/dist/observability-BYd-RzEx.js.map +0 -1
  131. package/dist/query-sQNO5vU_.js.map +0 -1
  132. package/dist/rebuild-index-DP4CqSSs.js.map +0 -1
  133. package/dist/restore-DpQYef6r.js.map +0 -1
  134. package/dist/shared-secret-BJdSwpgw.js.map +0 -1
  135. package/dist/src-CWpkSbvJ.js.map +0 -1
  136. package/dist/src-D24wDpzR.js +0 -6247
  137. package/dist/src-D24wDpzR.js.map +0 -1
  138. package/dist/src-Db4-qVtM.js.map +0 -1
  139. package/dist/subcommand-CP9NY2J4.js.map +0 -1
  140. package/dist/usage-CTfDq9HR.js.map +0 -1
  141. /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
package/dist/CHANGELOG.md CHANGED
@@ -1,5 +1,293 @@
1
1
  # @gusto/baerly-storage
2
2
 
3
+ ## 0.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 878bd78: Fail closed on ephemeral storage in production
8
+
9
+ `MemoryStorage` now refuses to construct in a detected deployment
10
+ (`NODE_ENV=production` or a known PaaS marker) unless you explicitly acknowledge
11
+ that it's ephemeral. This closes a silent-data-loss failure mode: an app that
12
+ falls back to in-memory storage in production, where writes "succeed" into
13
+ process RAM and vanish on every restart with no loud signal.
14
+
15
+ **What changed**
16
+
17
+ - `new MemoryStorage()` throws `BaerlyError("InvalidConfig")` in a detected
18
+ deployment. Tests and local dev are unaffected — neither sets those signals.
19
+ - New `resolveStorageFromEnv(env?)` export on `@gusto/baerly-storage/node`: the
20
+ safe, tested storage selector the Node example scaffolds now use, so apps
21
+ don't hand-roll one with a silent fallback.
22
+ - New `assertStorageReachable(storage)` export on `@gusto/baerly-storage/node`:
23
+ an opt-in boot/readiness check that fails closed on an unreachable or
24
+ CAS-broken bucket — the wrong-bucket-name gap a missing-bucket guard can't
25
+ catch.
26
+ - New pure `isDeployedEnv(env)` predicate on `@gusto/baerly-storage`.
27
+
28
+ **Migration**
29
+
30
+ - To run in-memory storage in a deployment on purpose (e.g. a throwaway demo),
31
+ opt in explicitly — either in code:
32
+
33
+ ```ts
34
+ new MemoryStorage({ ephemeral: true });
35
+ ```
36
+
37
+ or via the environment:
38
+
39
+ ```sh
40
+ BAERLY_ALLOW_EPHEMERAL_STORAGE=true
41
+ ```
42
+
43
+ - No action needed for tests, local dev, or apps already using a real S3/R2
44
+ bucket.
45
+
46
+ **Platform note**
47
+
48
+ - The guard is effectively Node-only. A Cloudflare Worker requires an R2
49
+ binding and has no silent in-memory fallback, and the deploy-detection
50
+ predicate reads `process.env`, which is empty on Workerd — so the guard never
51
+ fires (and never needs to) on Cloudflare.
52
+ - CI is never treated as deployed. When `CI` is set to a non-empty, non-`false`
53
+ value, PaaS-marker detection is suppressed, so `MemoryStorage` still
54
+ constructs in CI — including Kubernetes-hosted CI agents that set
55
+ `KUBERNETES_SERVICE_HOST`. An explicit `NODE_ENV=production` still trips the
56
+ guard.
57
+
58
+ - ab1d80e: Node apps can now run with zero storage credentials, using the new
59
+ `localFsStorage()` factory from `@gusto/baerly-storage/node`. The Node examples
60
+ default to local filesystem storage in development and promote to S3 or R2 once
61
+ bucket environment variables are set.
62
+
63
+ `localFsStorage()` is a local-dev convenience only — single-process, with no
64
+ cross-process CAS and no crash durability. So the Node example servers fail loud
65
+ in a detected deployment (`NODE_ENV=production` or a known PaaS) and require a
66
+ real bucket: a missing or typo'd bucket aborts startup instead of running
67
+ production on non-durable storage. There is deliberately no opt-in to run
68
+ local-fs in a deployment. When self-hosting without a cloud bucket, run MinIO on
69
+ the box or use SQLite + Litestream.
70
+
71
+ - 7ded765: Cloudflare Workers can now talk to S3-compatible storage over HTTP instead of a
72
+ native R2 binding. This is opt-in; the R2 binding remains the default.
73
+
74
+ New exports and options:
75
+
76
+ - New Worker-safe subpath `@gusto/baerly-storage/s3` exports `S3HttpStorage` and
77
+ `sigV4Signer`. Their closure pulls in no `node:` builtins, so it loads in a
78
+ Worker.
79
+ - `baerlyWorker` accepts an optional `storage` in its factory options. It
80
+ defaults to the `env.BUCKET` R2 binding.
81
+ - `BaerlyEnv.BUCKET` is now optional, so an S3-only Worker need not declare an R2
82
+ binding.
83
+
84
+ `sigV4Signer` fails fast with `InvalidConfig` when `accessKeyId`,
85
+ `secretAccessKey`, or `region` is empty or whitespace-only (for example, a blank
86
+ or accidentally-spaced wrangler `var`). This replaces signing with blank
87
+ credentials — or building a malformed empty-region SigV4 scope — and drawing an
88
+ opaque 403.
89
+
90
+ This path ships at the same support tier as AWS-via-`S3HttpStorage`:
91
+ credential-gated, with production validation owned by the operator. CI guards the
92
+ closure under workerd on two levels:
93
+
94
+ - a bundle probe that it stays `node:`-free (so it loads in a Worker), and
95
+ - an in-isolate wire test that `S3HttpStorage` + `sigV4Signer` actually run
96
+ there — signing, XML parse, request/response plumbing — against an in-memory
97
+ S3 stub.
98
+
99
+ CI does not drive a real S3 endpoint from workerd. Verify yours with `baerly
100
+ doctor --bucket` before relying on it. Note that `baerly deploy` and `doctor
101
+ --target=cloudflare` still expect an R2 binding in `wrangler.jsonc`.
102
+
103
+ - df232a4: Add IRSA (web-identity) credential support for S3 on EKS. Previously
104
+ `fromEksPodIdentity()` handled only the EKS Pod Identity agent
105
+ (`AWS_CONTAINER_CREDENTIALS_FULL_URI`). Clusters that inject credentials via
106
+ IRSA (`AWS_ROLE_ARN` + `AWS_WEB_IDENTITY_TOKEN_FILE`) threw `InvalidConfig` on
107
+ first sign, so every S3 call failed.
108
+
109
+ Two new credential providers in `@gusto/baerly-storage/node`:
110
+
111
+ - `fromWebIdentity()` — exchanges the projected service-account token for
112
+ short-lived credentials via STS `AssumeRoleWithWebIdentity`. The call is
113
+ unsigned; the token is the auth. It returns `expiration`, so the signing layer
114
+ rotates the ~1h credentials automatically. No AWS SDK dependency — it uses
115
+ `fetch` plus the existing hardened XML parser.
116
+ - `fromEks()` — auto-detects the mechanism on each resolve: Pod Identity when
117
+ `AWS_CONTAINER_CREDENTIALS_FULL_URI` is present, otherwise IRSA. It throws a
118
+ clear `InvalidConfig` when neither is configured. Prefer this over the
119
+ mechanism-specific providers unless you have a reason to pin one.
120
+
121
+ Both EKS providers now fail with actionable errors instead of a bare status. A
122
+ missing, unreadable, or empty projected token throws `InvalidConfig`. A failed
123
+ STS `AssumeRoleWithWebIdentity` call folds the STS error `Code`/`Message` (for
124
+ example, `InvalidIdentityToken`) into the thrown message, so credential
125
+ misconfigs are diagnosable at a glance.
126
+
127
+ `fromEksPodIdentity()` keeps its behavior; it only gains the same
128
+ `InvalidConfig` token-file guards.
129
+
130
+ - 73110de: Add public exports `PredicateArg` / `Predicate` / `Collection`; fix `Path<T>`
131
+ for optional array fields
132
+
133
+ **New public exports**
134
+
135
+ - `PredicateArg`, `Predicate`, and `Collection` are now exported from
136
+ `@gusto/baerly-storage`.
137
+ - `PredicateArg` is now exported from `@gusto/baerly-storage/client` (which
138
+ already exported `ClientCollection` and `Predicate`).
139
+
140
+ These let you name the `.where(...)` argument and predicate types directly
141
+ instead of hand-rolling a structural interface to accept a `Db` or a
142
+ `BaerlyClient`. The client handle type stays `ClientCollection`; the in-process
143
+ `Collection` type is root-only, because the client's HTTP handle is structurally
144
+ distinct (read-only `.where(...)`, `TerminalOptions`).
145
+
146
+ **Bug fix — optional array fields**
147
+
148
+ `Path<T>` (the dotted-path key type behind `Predicate<T>` and `.where(...)`) now
149
+ runs its leaf test on `NonNullable<T[K]>`, so `Path<{ tags?: string[] }>` is
150
+ `"tags"` — an optional array ends path recursion exactly like a required one.
151
+ Previously the `undefined` arm of `string[] | undefined` defeated the
152
+ array-is-a-leaf check and synthesized bogus `Array.prototype` keys (`tags.map…`),
153
+ which broke assignability of a bound `Db<Config>` / `BaerlyClient<Config>` to a
154
+ hand-rolled structural `collection(name: string)` interface — even for
155
+ collections that never used the array field.
156
+
157
+ **Migration**
158
+
159
+ No action required — both changes are additive. If you hand-rolled a structural
160
+ `collection(name: string)` shim to read collections by a runtime-computed name,
161
+ you can now import the real types or narrow at the boundary:
162
+
163
+ ```ts
164
+ (db as Db<UnboundConfig>).collection(name);
165
+ ```
166
+
167
+ ### Patch Changes
168
+
169
+ - 29bb00c: Refresh dependencies ahead of release. No public API changes.
170
+
171
+ Runtime deps that ship to consumers:
172
+
173
+ - `@logtape/logtape` 2.1.3 → 2.2.2
174
+ - `hono` 4.12.25 → 4.12.27
175
+ - `@hono/node-server` 2.0.4 → 2.0.6
176
+ - `jose` caret floor `^6.2.0` → `^6.2.3`
177
+
178
+ The `@gusto/create-baerly-storage` scaffolder picks up `@clack/prompts` 1.6.0.
179
+
180
+ The `@logtape/logtape` growth was rebaselined with a dated note in the
181
+ bundle-size budgets. (The XML parser was separately swapped from
182
+ `fast-xml-parser` to `@rgrove/parse-xml` — see the parser-swap changeset — which
183
+ removes `fast-xml-parser` and its transitive closure from the tree entirely.)
184
+
185
+ - 4813d9e: Swap `fast-xml-parser` for `@rgrove/parse-xml` in the S3 XML decode path
186
+ (`@baerly/adapter-node`). No public API changes — all exported functions and
187
+ types are unchanged.
188
+
189
+ **Smaller bundle:** −87 KiB raw / −24 KiB gz / −14 KiB min-gz on the `s3.js`
190
+ closure. `@rgrove/parse-xml` also has zero transitive dependencies, where
191
+ `fast-xml-parser` pulled in `strnum` and `@nodable/entities` — so the
192
+ supply-chain and audit surface both shrink.
193
+
194
+ **CVE-class defense-in-depth (not an active-hole fix):** `fast-xml-parser`
195
+ shipped ~6 CVEs across 5.x (CVE-2026-25896, CVE-2026-26278, CVE-2026-33036,
196
+ and others), all in the DOCTYPE/entity surface. Our `<!DOCTYPE` regex guard
197
+ already made those vectors unreachable — the pinned `fast-xml-parser@5.8.0`
198
+ was never itself vulnerable — but each new CVE still forced a version-pin
199
+ review. `@rgrove/parse-xml` parses and discards DTDs without resolving custom
200
+ entities, so the entity-expansion CVE _class_ cannot recur even if that regex
201
+ guard ever regressed. Removing the dependency also ends its dependabot cadence.
202
+
203
+ **Intended entity-set difference (not a bug):** `@rgrove/parse-xml` decodes
204
+ only the 5 predefined XML entities (`&amp; &lt; &gt; &quot; &apos;`) plus
205
+ decimal and hex numeric character references. It does NOT decode HTML named
206
+ entities (`&nbsp;`, `&mdash;`, etc.); the old code enabled `htmlEntities: true`
207
+ solely to get numeric refs. S3/R2/MinIO wire data is XML, not HTML — no backend
208
+ emits HTML-only named entities in `ListObjectsV2` or error responses — so the
209
+ narrower set is more spec-correct.
210
+
211
+ The swap was validated during development with a one-time differential-oracle
212
+ test asserting field-for-field parity between the two parsers on generated
213
+ S3-shaped XML (predefined entities, decimal/hex numeric refs, CDATA, singular
214
+ and plural `<Contents>`). That check is not retained; going forward, parser
215
+ behavior is pinned by the example-based contract tests in
216
+ `packages/adapter-node/src/xml.test.ts`.
217
+
218
+ - e18e9c4: Reject `.` / `..` / empty object keys at the Storage boundary
219
+
220
+ Every `Storage` adapter (`MemoryStorage`, `S3HttpStorage`, `r2BindingStorage`,
221
+ `LocalFsStorage`) now validates the key on `get` / `put` / `delete` and throws
222
+ `BaerlyError("InvalidConfig")` when the key is empty or has a `.` or `..`
223
+ segment in its `/`-delimited path. Such keys can't be addressed over the S3/R2
224
+ HTTP API: RFC 3986 dot-segment removal rewrites `<bucket>/.` to the bucket root
225
+ before the request is signed, so a naive PUT fails as a confusing bucket-root
226
+ `403` instead of a clear error. The check runs client-side, before any network
227
+ call, so every backend rejects identically and the behavior ports cleanly to
228
+ other languages.
229
+
230
+ **What changed**
231
+
232
+ - `get` / `put` / `delete` on all adapters reject `""`, `.`, `..`, and any key
233
+ with a `.` or `..` path segment, with `InvalidConfig`. `list(prefix)` is
234
+ unaffected — a prefix rides the `?prefix=` query component, where `.` / `..`
235
+ are harmless.
236
+ - The 1024-byte full-key ceiling is still enforced on the write path
237
+ (`assertKeyWithinLimit`), where multi-segment keys are assembled.
238
+
239
+ **Migration**
240
+
241
+ - No action for normal use. The kernel never emits these keys, and
242
+ caller-controlled segments (`_id`, `collection`, `app`, `tenant`) are already
243
+ screened one layer up. If you call a `Storage` adapter directly with a bare
244
+ `.` / `..` / empty key, catch `BaerlyError` and check `code === "InvalidConfig"`.
245
+ - Shipped as a patch, not a minor: these keys were never addressable — a
246
+ `.` / `..` / empty key already failed with an opaque bucket-root `403` — so no
247
+ working call site changes behavior.
248
+
249
+ - b8b87e5: Write down the durable-contract promises: LogEntry is versionless, version axes
250
+ are named and drift-gated, and backend capabilities are split into required vs.
251
+ optional
252
+
253
+ Documentation and internal tooling only. Nothing changes in the emitted bytes,
254
+ the public API, or runtime behavior — this just records compatibility promises
255
+ the project already relied on, so anyone building on the durable contract (the
256
+ CDC-style `LogEntry` export, the bucket layout) can depend on them in writing.
257
+
258
+ **LogEntry is versionless and additive-only (ADR-005, `docs/adr/005-logentry-versionless.md`)**
259
+
260
+ - `LogEntry` carries no `schema_version`; the live wire contract is owned by
261
+ `docs/spec/log-entry-shape.md`. Consumers **must ignore unknown keys** — a
262
+ compatible release can add new optional fields at any time. Renaming a field,
263
+ repurposing a value, removing a field, or widening `op` requires an explicit
264
+ compatibility decision, a migration note, and a versioned release.
265
+
266
+ **Version matrix + drift gate**
267
+
268
+ - `docs/contributing/version-matrix.json` names every version axis in one place:
269
+ package semver, `specVersion`, the per-artifact durable `schema_version`s, the
270
+ `layout_version` cordon, and a reserved conformance `corpusVersion`.
271
+ - `docs/contributing/conventions/versioning.md` states the pre-1.0 rules: no
272
+ breaking wire/schema/layout change ships as a patch; while `0.x` it takes a
273
+ minor plus a migration note.
274
+ - `scripts/check-version-matrix.ts` fails `verify` on drift — it derives
275
+ `specVersion` from the wire IR so the matrix can't diverge, and enforces
276
+ package lockstep plus the LogEntry/layout/corpus sentinels. `gen:version-matrix`
277
+ regenerates the artifact from the reference implementation.
278
+
279
+ **Required vs. optional storage capabilities**
280
+
281
+ - `docs/spec/capabilities.md` records what a backend MUST support to certify as
282
+ a full `Storage` (CAS — exactly-one-winner conditional create — is required,
283
+ not optional), what is optional, and a planned read-only `ReaderStorage` tier.
284
+
285
+ **Migration**
286
+
287
+ - No action required. Nothing in the emitted bytes, the public API, or runtime
288
+ behavior changes. `SNAPSHOT_SCHEMA_VERSION` replaces a `1` literal with a named
289
+ constant of the same value.
290
+
3
291
  ## 0.3.0
4
292
 
5
293
  ### Minor Changes
@@ -22,6 +310,7 @@
22
310
  changed since `0.2.0`. Reach out and I'll help you migrate.
23
311
 
24
312
  **Migrating from an internal build**
313
+
25
314
  - **Cheaper commits, and a breaking on-disk format (schema v3).** A write now
26
315
  costs 2 Class-A PUTs instead of 3 — appending the numbered `log/<seq>` entry
27
316
  _is_ the commit, so there is no separate `current.json` write. `current.json`
@@ -29,13 +318,13 @@
29
318
  `+mean_entry_bytes`, `−tail_bytes`), and readers discover the true tail by
30
319
  forward-probe. **Buckets written under schema v2 are rejected with no
31
320
  migration path** — re-create the bucket (or `admin dump` on a v2 build →
32
- `admin restore` on this one). See ADR-008.
321
+ `admin restore` on this one). See ADR-004.
33
322
  - **`Db.transaction` removed — the document is the atomic unit.** Single-document
34
323
  writes are each atomic; there is no batch. Replace
35
324
  `db.transaction(name, tx => { tx.update(a); tx.update(b) })` with individual
36
325
  `db.collection(name).update(...)` calls. The both-or-neither guarantee is
37
326
  gone; model a single document as your consistency boundary. Re-adding
38
- transactions later is additive (ADR-002).
327
+ transactions later is additive (under the API surface lock).
39
328
  - **Tighter key-segment validation.** One shared rule validates every
40
329
  caller-controlled segment (`_id`, `collection`, `app`, `tenant`), rejecting
41
330
  empty / `/` / `.` / `..` / control chars / reserved leading `_` / over-length
@@ -46,6 +335,7 @@
46
335
  same rule.
47
336
 
48
337
  **Fixed**
338
+
49
339
  - **The change feed no longer dies after 1024 writes to a collection.** The
50
340
  `/v1/since` cursor's sequence segment was 10-bit (`0..1023`); the 1025th write
51
341
  produced an invalid cursor the server then rejected with a `400`, permanently
@@ -90,12 +380,12 @@
90
380
 
91
381
  // after — factory bound to your defineConfig collections
92
382
  import { createBaerlyReact } from "@gusto/baerly-storage/client/react";
93
- const { Provider, useQuery, useMutation, useClient } = createBaerlyReact<typeof config>();
383
+ const { Provider, useQuery, useMutation, useClient } =
384
+ createBaerlyReact<typeof config>();
94
385
  ```
95
386
 
96
387
  The loose exports no longer exist; obtain the hooks from the factory so
97
- they are typed against your config. See ADR-002 (additive-only surface
98
- lock).
388
+ they are typed against your config (additive-only surface lock).
99
389
 
100
390
  ## 0.1.2
101
391
 
@@ -0,0 +1,125 @@
1
+ # baerly-storage — common mistakes & recipes
2
+
3
+ > Companion to `dist/API.md`. API.md is the surface; this file is the
4
+ > "why did my call fail" lookup, keyed by the exact error string you
5
+ > see. If a fix here disagrees with the `.d.ts` types, the types win.
6
+
7
+ ## Common mistakes (keyed by the error you see)
8
+
9
+ ### `Request body must be { doc: object }` (HTTP 400, `code="SchemaError"`)
10
+
11
+ **Cause:** POSTed a flat document body to `/v1/c/<collection>`.
12
+ **Fix:** Wrap it: `{ "doc": { ...yourFields } }`. The insert verb reads
13
+ `body.doc`, not the body itself. Same pattern for PATCH (`patch:`) and
14
+ PUT (`doc:`).
15
+ The wire `resolution` says: `Send a JSON body shaped { "doc": { ... } } for POST/PUT, or { "patch": { ... } } for PATCH.`
16
+
17
+ ### `BaerlyError code="SchemaError"` on insert/update/replace
18
+
19
+ **Cause:** the document failed schema validation, OR the body is not
20
+ valid JSON / contains an array where `DocumentValue` is required, OR a
21
+ `null` field value (use `.optional()`; `null` in an *update patch* is the
22
+ RFC 7386 deletion sentinel, not a storable value).
23
+ **Fix:** read `error.issues` (each `{ path, message }`) for the offending
24
+ field path. Declare `_id: z.string()` (required) in your schema — the
25
+ validator runs on the post-image, so optional `_id` is wrong.
26
+
27
+ ### `BaerlyError code="Conflict"` (HTTP 409)
28
+
29
+ **Cause:** the write conflicted with existing state. CAS conflicts are
30
+ retryable (`retriable: true`); duplicate caller-supplied `_id` inserts are
31
+ terminal (`retriable: false`).
32
+ **Fix:** follow the wire `resolution`. For retryable CAS conflicts, re-read,
33
+ re-apply, and retry with bounded backoff. For duplicate `_id` conflicts,
34
+ choose a different `_id`, or omit `_id` so baerly-storage can mint one.
35
+ The in-process writer already retries a bounded number of CAS attempts; a
36
+ remote client that sees `retriable: true` should apply its own bounded backoff.
37
+
38
+ ### `db.collection(name).insertOne(...)` / `.find(...)` is not a function
39
+
40
+ **Cause:** Mongo muscle memory. No such method.
41
+ **Fix:** `db.collection(name).insert(row)` and
42
+ `.where({ field: value }).all()` / `.where(q => q.gte("count", 1)).all()`.
43
+
44
+ ### `.useIndex(...)` / `.hint(...)` is not a function
45
+
46
+ **Cause:** SQL/ORM muscle memory. No such method.
47
+ **Fix:** the planner picks the index automatically from the
48
+ `IndexDefinition`s registered in `baerly.config.ts`.
49
+
50
+ ### `BaerlyError code="InvalidConfig"` — `baerly: no auth configured`
51
+
52
+ **Full message:** `baerly: no auth configured. Set \`auth\` in baerly.config.ts ("none", "shared-secret") or pass \`verifier\` on the adapter factory.`
53
+
54
+ **Cause:** the adapter resolved no `Verifier`.
55
+ **Fix:** set `auth` in `baerly.config.ts` (`"none"` or `"shared-secret"`)
56
+ or pass `verifier:` on the adapter factory.
57
+
58
+ ### `BaerlyError code="InvalidConfig"` — `SHARED_SECRET env is empty/unset`
59
+
60
+ **Full message:** `baerly: auth="shared-secret" but SHARED_SECRET env is empty/unset. Cloudflare: \`wrangler secret put SHARED_SECRET\`, or add to .dev.vars for local dev. Node: set in process env.`
61
+
62
+ **Cause:** `auth: "shared-secret"` was set but the `SHARED_SECRET`
63
+ environment variable is missing or empty at startup.
64
+ **Fix:** set the `SHARED_SECRET` env (`wrangler secret put SHARED_SECRET`
65
+ on Cloudflare, `.dev.vars` for local dev, process env on Node).
66
+
67
+ ### `BaerlyError code="InvalidConfig"` — `Refusing to start: no durable storage configured` / `Refusing to use in-memory storage`
68
+
69
+ **Cause:** a deployed process (`NODE_ENV=production` or a known PaaS marker)
70
+ reached storage selection with no real bucket configured — or constructed
71
+ `MemoryStorage` there. In-memory "succeeds" into RAM and vanishes on every
72
+ restart; local-fs is single-process with no cross-process CAS. Both are
73
+ refused in a deployment so the failure is loud at boot, not silent data loss
74
+ in production.
75
+ **Fix:** don't hand-roll storage selection — call `resolveStorageFromEnv()`
76
+ from `@gusto/baerly-storage/node` (`R2_ACCOUNT_ID` → R2, `BUCKET` → S3, else
77
+ local-fs in dev) and configure a bucket: `BUCKET` + `AWS_ACCESS_KEY_ID` +
78
+ `AWS_SECRET_ACCESS_KEY` (add `R2_ACCOUNT_ID` for R2). To catch an
79
+ unreachable or CAS-broken bucket at boot rather than on the first write,
80
+ `await assertStorageReachable(storage)`. Intentionally ephemeral (a throwaway
81
+ demo)? Opt in explicitly: `new MemoryStorage({ ephemeral: true })` or
82
+ `BAERLY_ALLOW_EPHEMERAL_STORAGE=true`.
83
+
84
+ ### `BaerlyError code="UseQueryAwaitedRecorder"`
85
+
86
+ **Cause:** awaited a terminal (`.get`/`.first`/`.all`/`.count`) inside a
87
+ `useQuery` callback. The recorder is synchronous; awaiting it yields a
88
+ sentinel and the next property access throws.
89
+ **Fix:** don't `await` in `useQuery` — for compound reads use
90
+ `Promise.all` (parallel) or compose two `useQuery` calls with
91
+ `useQuery.skip` (dependent). For writes use `useMutation()`.
92
+
93
+ ### `BaerlyError code="UnexpectedWriteInQuery"`
94
+
95
+ **Cause:** called a write verb (`insert`/`update`/`replace`/`delete`)
96
+ inside a `useQuery` callback.
97
+ **Fix:** reads go in `useQuery`, writes go in `useMutation()`.
98
+
99
+ ## Anti-patterns (compile-clean but wrong)
100
+
101
+ - Don't reach into `node_modules/@gusto/baerly-storage/dist/` at runtime —
102
+ consume the published exports.
103
+ - Don't widen branded types (`UUID`, `ContentVersionId`) with `as string`.
104
+ - Don't put `SHARED_SECRET` in the SPA bundle — it is server-to-server
105
+ only.
106
+ - Don't mutate `VerifierResult.tenantPrefix` between the verifier and
107
+ `Db.create` — the dispatcher pins the tenant from the verifier's return.
108
+ - `z.string().nullable()` in a schema — `DocumentValue` excludes `null`.
109
+ - Raw SQL / `WHERE` clauses / hand-built query AST — the only query
110
+ surface is the `.where(...)` method chain.
111
+ - `.all()` on a hot path — page or cursor-iterate; `.all()` is for
112
+ bounded result sets.
113
+ - Relying on baerly to cap or scope a read. `GET /v1/c/:collection` (and
114
+ `.all()`) returns the **whole collection** — there is no default row
115
+ cap, and auth pins a tenant, not a row owner. Scope non-owner reads in
116
+ your own route: inject a `where owner_id = <verified id>` predicate
117
+ (ideally index-backed) and clamp `limit = min(requested ?? MAX, MAX)`.
118
+ Rejecting `?limit` backfires — it forces the uncapped path. See
119
+ `docs/guide/auth.md` § Authorization Boundary.
120
+
121
+ ## Where to look next
122
+
123
+ - Public API surface: `dist/API.md` (`cat node_modules/@gusto/baerly-storage/dist/API.md`).
124
+ - Per-symbol types: the `dist/*.d.ts` chunks.
125
+ - A remembered call no longer type-checks: `dist/CHANGELOG.md`.
@@ -9,7 +9,7 @@ This file is generated at build time from each dependency's own LICENSE
9
9
  file and is not hand-maintained.
10
10
 
11
11
  ==============================================================================
12
- @hono/node-server@2.0.4
12
+ @hono/node-server@2.0.6
13
13
  License: MIT
14
14
  Repository: git+https://github.com/honojs/node-server.git
15
15
 
@@ -36,13 +36,13 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
36
36
  SOFTWARE.
37
37
 
38
38
  ==============================================================================
39
- @logtape/logtape@2.1.3
39
+ @logtape/logtape@2.2.2
40
40
  License: MIT
41
41
  Repository: git+https://github.com/dahlia/logtape.git
42
42
 
43
43
  MIT License
44
44
 
45
- Copyright 2024–2025 Hong Minhee
45
+ Copyright 2024–2026 Hong Minhee
46
46
 
47
47
  Permission is hereby granted, free of charge, to any person obtaining a copy of
48
48
  this software and associated documentation files (the "Software"), to deal in
@@ -62,11 +62,25 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
62
62
  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
63
63
 
64
64
  ==============================================================================
65
- @nodable/entities@2.1.0
66
- License: MIT
67
- Repository: git+https://github.com/nodable/val-parsers.git
65
+ @rgrove/parse-xml@4.2.1
66
+ License: ISC
67
+ Repository: https://github.com/rgrove/parse-xml.git
68
+
69
+ ISC License
70
+
71
+ Copyright Ryan Grove <ryan@wonko.com>
72
+
73
+ Permission to use, copy, modify, and/or distribute this software for any purpose
74
+ with or without fee is hereby granted, provided that the above copyright notice
75
+ and this permission notice appear in all copies.
68
76
 
69
- (no license text found in package)
77
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
78
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
79
+ FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
80
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
81
+ OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
82
+ TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
83
+ THIS SOFTWARE.
70
84
 
71
85
  ==============================================================================
72
86
  aws4fetch@1.0.20
@@ -121,34 +135,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
121
135
  SOFTWARE.
122
136
 
123
137
  ==============================================================================
124
- fast-xml-parser@5.8.0
125
- License: MIT
126
- Repository: git+https://github.com/NaturalIntelligence/fast-xml-parser.git
127
-
128
- MIT License
129
-
130
- Copyright (c) 2017 Amit Kumar Gupta
131
-
132
- Permission is hereby granted, free of charge, to any person obtaining a copy
133
- of this software and associated documentation files (the "Software"), to deal
134
- in the Software without restriction, including without limitation the rights
135
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
136
- copies of the Software, and to permit persons to whom the Software is
137
- furnished to do so, subject to the following conditions:
138
-
139
- The above copyright notice and this permission notice shall be included in all
140
- copies or substantial portions of the Software.
141
-
142
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
143
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
144
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
145
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
146
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
147
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
148
- SOFTWARE.
149
-
150
- ==============================================================================
151
- hono@4.12.25
138
+ hono@4.12.27
152
139
  License: MIT
153
140
  Repository: git+https://github.com/honojs/hono.git
154
141
 
@@ -228,33 +215,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
228
215
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
229
216
  SOFTWARE.
230
217
 
231
- ==============================================================================
232
- path-expression-matcher@1.5.0
233
- License: MIT
234
- Repository: https://github.com/NaturalIntelligence/path-expression-matcher
235
-
236
- MIT License
237
-
238
- Copyright (c) 2024
239
-
240
- Permission is hereby granted, free of charge, to any person obtaining a copy
241
- of this software and associated documentation files (the "Software"), to deal
242
- in the Software without restriction, including without limitation the rights
243
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
244
- copies of the Software, and to permit persons to whom the Software is
245
- furnished to do so, subject to the following conditions:
246
-
247
- The above copyright notice and this permission notice shall be included in all
248
- copies or substantial portions of the Software.
249
-
250
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
251
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
252
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
253
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
254
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
255
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
256
- SOFTWARE.
257
-
258
218
  ==============================================================================
259
219
  picocolors@1.1.1
260
220
  License: ISC
@@ -276,37 +236,3 @@ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
276
236
  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
277
237
  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
278
238
 
279
- ==============================================================================
280
- strnum@2.3.0
281
- License: MIT
282
- Repository: https://github.com/NaturalIntelligence/strnum
283
-
284
- MIT License
285
-
286
- Copyright (c) 2021 Natural Intelligence
287
-
288
- Permission is hereby granted, free of charge, to any person obtaining a copy
289
- of this software and associated documentation files (the "Software"), to deal
290
- in the Software without restriction, including without limitation the rights
291
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
292
- copies of the Software, and to permit persons to whom the Software is
293
- furnished to do so, subject to the following conditions:
294
-
295
- The above copyright notice and this permission notice shall be included in all
296
- copies or substantial portions of the Software.
297
-
298
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
299
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
300
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
301
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
302
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
303
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
304
- SOFTWARE.
305
-
306
- ==============================================================================
307
- xml-naming@0.1.0
308
- License: MIT
309
- Repository: https://github.com/NaturalIntelligence/xml-naming
310
-
311
- (no license text found in package)
312
-