@gusto/baerly-storage 0.3.0 → 0.4.1

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 +301 -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-_GTdeSMo.js +391 -0
  96. package/dist/runtime-spec-_GTdeSMo.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-Db4-qVtM.js → src-CYHFDrKz.js} +51 -8
  104. package/dist/src-CYHFDrKz.js.map +1 -0
  105. package/dist/{src-CWpkSbvJ.js → src-DYZ4H1aF.js} +6 -5
  106. package/dist/src-DYZ4H1aF.js.map +1 -0
  107. package/dist/src-D__mHQmQ.js +2271 -0
  108. package/dist/src-D__mHQmQ.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 +51 -27
  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,299 @@
1
1
  # @gusto/baerly-storage
2
2
 
3
+ ## 0.4.1
4
+
5
+ ### Patch Changes
6
+
7
+ - Stamp the correct kernelVersion into the served /v1/spec. 0.4.0 shipped kernelVersion "0.3.0" because changeset:version did not regenerate baerly.spec.json; gen:spec now runs on every bump.
8
+
9
+ ## 0.4.0
10
+
11
+ ### Minor Changes
12
+
13
+ - 878bd78: Fail closed on ephemeral storage in production
14
+
15
+ `MemoryStorage` now refuses to construct in a detected deployment
16
+ (`NODE_ENV=production` or a known PaaS marker) unless you explicitly acknowledge
17
+ that it's ephemeral. This closes a silent-data-loss failure mode: an app that
18
+ falls back to in-memory storage in production, where writes "succeed" into
19
+ process RAM and vanish on every restart with no loud signal.
20
+
21
+ **What changed**
22
+
23
+ - `new MemoryStorage()` throws `BaerlyError("InvalidConfig")` in a detected
24
+ deployment. Tests and local dev are unaffected — neither sets those signals.
25
+ - New `resolveStorageFromEnv(env?)` export on `@gusto/baerly-storage/node`: the
26
+ safe, tested storage selector the Node example scaffolds now use, so apps
27
+ don't hand-roll one with a silent fallback.
28
+ - New `assertStorageReachable(storage)` export on `@gusto/baerly-storage/node`:
29
+ an opt-in boot/readiness check that fails closed on an unreachable or
30
+ CAS-broken bucket — the wrong-bucket-name gap a missing-bucket guard can't
31
+ catch.
32
+ - New pure `isDeployedEnv(env)` predicate on `@gusto/baerly-storage`.
33
+
34
+ **Migration**
35
+
36
+ - To run in-memory storage in a deployment on purpose (e.g. a throwaway demo),
37
+ opt in explicitly — either in code:
38
+
39
+ ```ts
40
+ new MemoryStorage({ ephemeral: true });
41
+ ```
42
+
43
+ or via the environment:
44
+
45
+ ```sh
46
+ BAERLY_ALLOW_EPHEMERAL_STORAGE=true
47
+ ```
48
+
49
+ - No action needed for tests, local dev, or apps already using a real S3/R2
50
+ bucket.
51
+
52
+ **Platform note**
53
+
54
+ - The guard is effectively Node-only. A Cloudflare Worker requires an R2
55
+ binding and has no silent in-memory fallback, and the deploy-detection
56
+ predicate reads `process.env`, which is empty on Workerd — so the guard never
57
+ fires (and never needs to) on Cloudflare.
58
+ - CI is never treated as deployed. When `CI` is set to a non-empty, non-`false`
59
+ value, PaaS-marker detection is suppressed, so `MemoryStorage` still
60
+ constructs in CI — including Kubernetes-hosted CI agents that set
61
+ `KUBERNETES_SERVICE_HOST`. An explicit `NODE_ENV=production` still trips the
62
+ guard.
63
+
64
+ - ab1d80e: Node apps can now run with zero storage credentials, using the new
65
+ `localFsStorage()` factory from `@gusto/baerly-storage/node`. The Node examples
66
+ default to local filesystem storage in development and promote to S3 or R2 once
67
+ bucket environment variables are set.
68
+
69
+ `localFsStorage()` is a local-dev convenience only — single-process, with no
70
+ cross-process CAS and no crash durability. So the Node example servers fail loud
71
+ in a detected deployment (`NODE_ENV=production` or a known PaaS) and require a
72
+ real bucket: a missing or typo'd bucket aborts startup instead of running
73
+ production on non-durable storage. There is deliberately no opt-in to run
74
+ local-fs in a deployment. When self-hosting without a cloud bucket, run MinIO on
75
+ the box or use SQLite + Litestream.
76
+
77
+ - 7ded765: Cloudflare Workers can now talk to S3-compatible storage over HTTP instead of a
78
+ native R2 binding. This is opt-in; the R2 binding remains the default.
79
+
80
+ New exports and options:
81
+
82
+ - New Worker-safe subpath `@gusto/baerly-storage/s3` exports `S3HttpStorage` and
83
+ `sigV4Signer`. Their closure pulls in no `node:` builtins, so it loads in a
84
+ Worker.
85
+ - `baerlyWorker` accepts an optional `storage` in its factory options. It
86
+ defaults to the `env.BUCKET` R2 binding.
87
+ - `BaerlyEnv.BUCKET` is now optional, so an S3-only Worker need not declare an R2
88
+ binding.
89
+
90
+ `sigV4Signer` fails fast with `InvalidConfig` when `accessKeyId`,
91
+ `secretAccessKey`, or `region` is empty or whitespace-only (for example, a blank
92
+ or accidentally-spaced wrangler `var`). This replaces signing with blank
93
+ credentials — or building a malformed empty-region SigV4 scope — and drawing an
94
+ opaque 403.
95
+
96
+ This path ships at the same support tier as AWS-via-`S3HttpStorage`:
97
+ credential-gated, with production validation owned by the operator. CI guards the
98
+ closure under workerd on two levels:
99
+
100
+ - a bundle probe that it stays `node:`-free (so it loads in a Worker), and
101
+ - an in-isolate wire test that `S3HttpStorage` + `sigV4Signer` actually run
102
+ there — signing, XML parse, request/response plumbing — against an in-memory
103
+ S3 stub.
104
+
105
+ CI does not drive a real S3 endpoint from workerd. Verify yours with `baerly
106
+ doctor --bucket` before relying on it. Note that `baerly deploy` and `doctor
107
+ --target=cloudflare` still expect an R2 binding in `wrangler.jsonc`.
108
+
109
+ - df232a4: Add IRSA (web-identity) credential support for S3 on EKS. Previously
110
+ `fromEksPodIdentity()` handled only the EKS Pod Identity agent
111
+ (`AWS_CONTAINER_CREDENTIALS_FULL_URI`). Clusters that inject credentials via
112
+ IRSA (`AWS_ROLE_ARN` + `AWS_WEB_IDENTITY_TOKEN_FILE`) threw `InvalidConfig` on
113
+ first sign, so every S3 call failed.
114
+
115
+ Two new credential providers in `@gusto/baerly-storage/node`:
116
+
117
+ - `fromWebIdentity()` — exchanges the projected service-account token for
118
+ short-lived credentials via STS `AssumeRoleWithWebIdentity`. The call is
119
+ unsigned; the token is the auth. It returns `expiration`, so the signing layer
120
+ rotates the ~1h credentials automatically. No AWS SDK dependency — it uses
121
+ `fetch` plus the existing hardened XML parser.
122
+ - `fromEks()` — auto-detects the mechanism on each resolve: Pod Identity when
123
+ `AWS_CONTAINER_CREDENTIALS_FULL_URI` is present, otherwise IRSA. It throws a
124
+ clear `InvalidConfig` when neither is configured. Prefer this over the
125
+ mechanism-specific providers unless you have a reason to pin one.
126
+
127
+ Both EKS providers now fail with actionable errors instead of a bare status. A
128
+ missing, unreadable, or empty projected token throws `InvalidConfig`. A failed
129
+ STS `AssumeRoleWithWebIdentity` call folds the STS error `Code`/`Message` (for
130
+ example, `InvalidIdentityToken`) into the thrown message, so credential
131
+ misconfigs are diagnosable at a glance.
132
+
133
+ `fromEksPodIdentity()` keeps its behavior; it only gains the same
134
+ `InvalidConfig` token-file guards.
135
+
136
+ - 73110de: Add public exports `PredicateArg` / `Predicate` / `Collection`; fix `Path<T>`
137
+ for optional array fields
138
+
139
+ **New public exports**
140
+
141
+ - `PredicateArg`, `Predicate`, and `Collection` are now exported from
142
+ `@gusto/baerly-storage`.
143
+ - `PredicateArg` is now exported from `@gusto/baerly-storage/client` (which
144
+ already exported `ClientCollection` and `Predicate`).
145
+
146
+ These let you name the `.where(...)` argument and predicate types directly
147
+ instead of hand-rolling a structural interface to accept a `Db` or a
148
+ `BaerlyClient`. The client handle type stays `ClientCollection`; the in-process
149
+ `Collection` type is root-only, because the client's HTTP handle is structurally
150
+ distinct (read-only `.where(...)`, `TerminalOptions`).
151
+
152
+ **Bug fix — optional array fields**
153
+
154
+ `Path<T>` (the dotted-path key type behind `Predicate<T>` and `.where(...)`) now
155
+ runs its leaf test on `NonNullable<T[K]>`, so `Path<{ tags?: string[] }>` is
156
+ `"tags"` — an optional array ends path recursion exactly like a required one.
157
+ Previously the `undefined` arm of `string[] | undefined` defeated the
158
+ array-is-a-leaf check and synthesized bogus `Array.prototype` keys (`tags.map…`),
159
+ which broke assignability of a bound `Db<Config>` / `BaerlyClient<Config>` to a
160
+ hand-rolled structural `collection(name: string)` interface — even for
161
+ collections that never used the array field.
162
+
163
+ **Migration**
164
+
165
+ No action required — both changes are additive. If you hand-rolled a structural
166
+ `collection(name: string)` shim to read collections by a runtime-computed name,
167
+ you can now import the real types or narrow at the boundary:
168
+
169
+ ```ts
170
+ (db as Db<UnboundConfig>).collection(name);
171
+ ```
172
+
173
+ ### Patch Changes
174
+
175
+ - 29bb00c: Refresh dependencies ahead of release. No public API changes.
176
+
177
+ Runtime deps that ship to consumers:
178
+
179
+ - `@logtape/logtape` 2.1.3 → 2.2.2
180
+ - `hono` 4.12.25 → 4.12.27
181
+ - `@hono/node-server` 2.0.4 → 2.0.6
182
+ - `jose` caret floor `^6.2.0` → `^6.2.3`
183
+
184
+ The `@gusto/create-baerly-storage` scaffolder picks up `@clack/prompts` 1.6.0.
185
+
186
+ The `@logtape/logtape` growth was rebaselined with a dated note in the
187
+ bundle-size budgets. (The XML parser was separately swapped from
188
+ `fast-xml-parser` to `@rgrove/parse-xml` — see the parser-swap changeset — which
189
+ removes `fast-xml-parser` and its transitive closure from the tree entirely.)
190
+
191
+ - 4813d9e: Swap `fast-xml-parser` for `@rgrove/parse-xml` in the S3 XML decode path
192
+ (`@baerly/adapter-node`). No public API changes — all exported functions and
193
+ types are unchanged.
194
+
195
+ **Smaller bundle:** −87 KiB raw / −24 KiB gz / −14 KiB min-gz on the `s3.js`
196
+ closure. `@rgrove/parse-xml` also has zero transitive dependencies, where
197
+ `fast-xml-parser` pulled in `strnum` and `@nodable/entities` — so the
198
+ supply-chain and audit surface both shrink.
199
+
200
+ **CVE-class defense-in-depth (not an active-hole fix):** `fast-xml-parser`
201
+ shipped ~6 CVEs across 5.x (CVE-2026-25896, CVE-2026-26278, CVE-2026-33036,
202
+ and others), all in the DOCTYPE/entity surface. Our `<!DOCTYPE` regex guard
203
+ already made those vectors unreachable — the pinned `fast-xml-parser@5.8.0`
204
+ was never itself vulnerable — but each new CVE still forced a version-pin
205
+ review. `@rgrove/parse-xml` parses and discards DTDs without resolving custom
206
+ entities, so the entity-expansion CVE _class_ cannot recur even if that regex
207
+ guard ever regressed. Removing the dependency also ends its dependabot cadence.
208
+
209
+ **Intended entity-set difference (not a bug):** `@rgrove/parse-xml` decodes
210
+ only the 5 predefined XML entities (`&amp; &lt; &gt; &quot; &apos;`) plus
211
+ decimal and hex numeric character references. It does NOT decode HTML named
212
+ entities (`&nbsp;`, `&mdash;`, etc.); the old code enabled `htmlEntities: true`
213
+ solely to get numeric refs. S3/R2/MinIO wire data is XML, not HTML — no backend
214
+ emits HTML-only named entities in `ListObjectsV2` or error responses — so the
215
+ narrower set is more spec-correct.
216
+
217
+ The swap was validated during development with a one-time differential-oracle
218
+ test asserting field-for-field parity between the two parsers on generated
219
+ S3-shaped XML (predefined entities, decimal/hex numeric refs, CDATA, singular
220
+ and plural `<Contents>`). That check is not retained; going forward, parser
221
+ behavior is pinned by the example-based contract tests in
222
+ `packages/adapter-node/src/xml.test.ts`.
223
+
224
+ - e18e9c4: Reject `.` / `..` / empty object keys at the Storage boundary
225
+
226
+ Every `Storage` adapter (`MemoryStorage`, `S3HttpStorage`, `r2BindingStorage`,
227
+ `LocalFsStorage`) now validates the key on `get` / `put` / `delete` and throws
228
+ `BaerlyError("InvalidConfig")` when the key is empty or has a `.` or `..`
229
+ segment in its `/`-delimited path. Such keys can't be addressed over the S3/R2
230
+ HTTP API: RFC 3986 dot-segment removal rewrites `<bucket>/.` to the bucket root
231
+ before the request is signed, so a naive PUT fails as a confusing bucket-root
232
+ `403` instead of a clear error. The check runs client-side, before any network
233
+ call, so every backend rejects identically and the behavior ports cleanly to
234
+ other languages.
235
+
236
+ **What changed**
237
+
238
+ - `get` / `put` / `delete` on all adapters reject `""`, `.`, `..`, and any key
239
+ with a `.` or `..` path segment, with `InvalidConfig`. `list(prefix)` is
240
+ unaffected — a prefix rides the `?prefix=` query component, where `.` / `..`
241
+ are harmless.
242
+ - The 1024-byte full-key ceiling is still enforced on the write path
243
+ (`assertKeyWithinLimit`), where multi-segment keys are assembled.
244
+
245
+ **Migration**
246
+
247
+ - No action for normal use. The kernel never emits these keys, and
248
+ caller-controlled segments (`_id`, `collection`, `app`, `tenant`) are already
249
+ screened one layer up. If you call a `Storage` adapter directly with a bare
250
+ `.` / `..` / empty key, catch `BaerlyError` and check `code === "InvalidConfig"`.
251
+ - Shipped as a patch, not a minor: these keys were never addressable — a
252
+ `.` / `..` / empty key already failed with an opaque bucket-root `403` — so no
253
+ working call site changes behavior.
254
+
255
+ - b8b87e5: Write down the durable-contract promises: LogEntry is versionless, version axes
256
+ are named and drift-gated, and backend capabilities are split into required vs.
257
+ optional
258
+
259
+ Documentation and internal tooling only. Nothing changes in the emitted bytes,
260
+ the public API, or runtime behavior — this just records compatibility promises
261
+ the project already relied on, so anyone building on the durable contract (the
262
+ CDC-style `LogEntry` export, the bucket layout) can depend on them in writing.
263
+
264
+ **LogEntry is versionless and additive-only (ADR-005, `docs/adr/005-logentry-versionless.md`)**
265
+
266
+ - `LogEntry` carries no `schema_version`; the live wire contract is owned by
267
+ `docs/spec/log-entry-shape.md`. Consumers **must ignore unknown keys** — a
268
+ compatible release can add new optional fields at any time. Renaming a field,
269
+ repurposing a value, removing a field, or widening `op` requires an explicit
270
+ compatibility decision, a migration note, and a versioned release.
271
+
272
+ **Version matrix + drift gate**
273
+
274
+ - `docs/contributing/version-matrix.json` names every version axis in one place:
275
+ package semver, `specVersion`, the per-artifact durable `schema_version`s, the
276
+ `layout_version` cordon, and a reserved conformance `corpusVersion`.
277
+ - `docs/contributing/conventions/versioning.md` states the pre-1.0 rules: no
278
+ breaking wire/schema/layout change ships as a patch; while `0.x` it takes a
279
+ minor plus a migration note.
280
+ - `scripts/check-version-matrix.ts` fails `verify` on drift — it derives
281
+ `specVersion` from the wire IR so the matrix can't diverge, and enforces
282
+ package lockstep plus the LogEntry/layout/corpus sentinels. `gen:version-matrix`
283
+ regenerates the artifact from the reference implementation.
284
+
285
+ **Required vs. optional storage capabilities**
286
+
287
+ - `docs/spec/capabilities.md` records what a backend MUST support to certify as
288
+ a full `Storage` (CAS — exactly-one-winner conditional create — is required,
289
+ not optional), what is optional, and a planned read-only `ReaderStorage` tier.
290
+
291
+ **Migration**
292
+
293
+ - No action required. Nothing in the emitted bytes, the public API, or runtime
294
+ behavior changes. `SNAPSHOT_SCHEMA_VERSION` replaces a `1` literal with a named
295
+ constant of the same value.
296
+
3
297
  ## 0.3.0
4
298
 
5
299
  ### Minor Changes
@@ -22,6 +316,7 @@
22
316
  changed since `0.2.0`. Reach out and I'll help you migrate.
23
317
 
24
318
  **Migrating from an internal build**
319
+
25
320
  - **Cheaper commits, and a breaking on-disk format (schema v3).** A write now
26
321
  costs 2 Class-A PUTs instead of 3 — appending the numbered `log/<seq>` entry
27
322
  _is_ the commit, so there is no separate `current.json` write. `current.json`
@@ -29,13 +324,13 @@
29
324
  `+mean_entry_bytes`, `−tail_bytes`), and readers discover the true tail by
30
325
  forward-probe. **Buckets written under schema v2 are rejected with no
31
326
  migration path** — re-create the bucket (or `admin dump` on a v2 build →
32
- `admin restore` on this one). See ADR-008.
327
+ `admin restore` on this one). See ADR-004.
33
328
  - **`Db.transaction` removed — the document is the atomic unit.** Single-document
34
329
  writes are each atomic; there is no batch. Replace
35
330
  `db.transaction(name, tx => { tx.update(a); tx.update(b) })` with individual
36
331
  `db.collection(name).update(...)` calls. The both-or-neither guarantee is
37
332
  gone; model a single document as your consistency boundary. Re-adding
38
- transactions later is additive (ADR-002).
333
+ transactions later is additive (under the API surface lock).
39
334
  - **Tighter key-segment validation.** One shared rule validates every
40
335
  caller-controlled segment (`_id`, `collection`, `app`, `tenant`), rejecting
41
336
  empty / `/` / `.` / `..` / control chars / reserved leading `_` / over-length
@@ -46,6 +341,7 @@
46
341
  same rule.
47
342
 
48
343
  **Fixed**
344
+
49
345
  - **The change feed no longer dies after 1024 writes to a collection.** The
50
346
  `/v1/since` cursor's sequence segment was 10-bit (`0..1023`); the 1025th write
51
347
  produced an invalid cursor the server then rejected with a `400`, permanently
@@ -90,12 +386,12 @@
90
386
 
91
387
  // after — factory bound to your defineConfig collections
92
388
  import { createBaerlyReact } from "@gusto/baerly-storage/client/react";
93
- const { Provider, useQuery, useMutation, useClient } = createBaerlyReact<typeof config>();
389
+ const { Provider, useQuery, useMutation, useClient } =
390
+ createBaerlyReact<typeof config>();
94
391
  ```
95
392
 
96
393
  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).
394
+ they are typed against your config (additive-only surface lock).
99
395
 
100
396
  ## 0.1.2
101
397
 
@@ -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
-