@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/README.md CHANGED
@@ -1,60 +1,74 @@
1
1
  # baerly-storage
2
2
 
3
- **Storage is the missing primitive for agent-built software, and all you need is a library.**
4
-
5
- > _Open source (Apache-2.0). Published as
6
- > [`@gusto/baerly-storage`](https://www.npmjs.com/package/@gusto/baerly-storage)
7
- > on npm._
8
-
9
- `baerly-storage` is a library that turns AWS S3, Cloudflare R2, or a
10
- conformant S3-compatible bucket into a document database. **There is
11
- no runtime. None.** No Baerly daemon, no leader, no scheduler, no
12
- catalog, no database service bill, no on-call. Coordination rides the
13
- request path — Cloudflare can finish bounded maintenance with `ctx.waitUntil`,
14
- Node runs it inline — and the only persistent component is your bucket.
15
-
16
- The server bundles is ~100 KB gzipped, and the browser client is ~5 KB gzipped.
17
- The whole public API fits in a single ~12k-token `dist/API.md` — small enough
18
- that an LLM can hold it in context.
19
-
20
- [S3 does the hard parts](https://aws.amazon.com/blogs/aws/amazon-s3-update-strong-read-after-write-consistency/),
21
- `baerly-storage` is the coordination that fixes the API. Built like git:
22
- content-addressed documents, immutable numbered log entries, and one
23
- conditional log create as the commit, per collection. Document model,
24
- live queries, snapshot isolation — the whole surface in a `.d.ts`
25
- designed for zero-shot use.
26
-
27
- Apps sized for this primitive — small, server-only writes, ~10 GB
28
- ceiling, mechanical exit to Postgres when they cross it — get a tool
29
- that matches their shape instead of a stack that doesn't.
3
+ **A database with no server. No daemon. No database runtime. Just your app and a bucket.**
30
4
 
31
- ```
32
- Compute → FaaS
33
- Tokens → LLM API
34
- Storage → this.
5
+ A document database that lives _in_ an S3/R2 bucket you already own. No new vendor to clear, nothing resident to keep running, and an API small enough for an open-weights LLM to zero-shot.
6
+
7
+ ```text
8
+ before: client → app handler → database server (a server)
9
+ after: client → app handler → S3/R2 bucket (just storage)
35
10
  ```
36
11
 
37
- Almost every team already has an object-storage bucket — for exports,
38
- backups, CSV graveyards. The security review happened years ago; the
39
- budget exists.
12
+ The trick is to cram the entire database execution layer inside an HTTP
13
+ request. There is no server, daemon, or coordinator: each read or
14
+ write runs as library code inside your request handler, the bucket
15
+ holds the data, and the protocol supplies the commit rules.
16
+
17
+ The load-bearing operation is narrow — one conditional create of the next
18
+ log object commits a write. When the request ends, baerly-storage is gone. Poof!
19
+
20
+ - **An API small enough to hold in your context.** No DDL, no raw SQL —
21
+ 8 verbs and a ~12k-token surface you can hand to an LLM or a
22
+ non-engineer and walk away.
23
+ - **Idle rounds to zero.** No database process to keep warm, and no
24
+ per-app database floor across a fleet of small internal tools.
25
+ - **No data hostage.** `baerly export --target=postgres` gives you a
26
+ per-collection SQL snapshot. Crossing the envelope is the graduation
27
+ signal; the data exit is mechanical.
28
+ - **No new vendor.** Your S3/R2 bucket cleared security review years
29
+ ago; every hosted alternative means a fresh vendor review and an IT
30
+ ticket for a new managed-DB SKU.
31
+ - **Nothing to go down.** No resident service in your critical path, one
32
+ fewer failure domain. Servers that don't exist can't go down.
33
+ - **Built like git.** Content-addressed documents, immutable numbered log
34
+ entries, and one conditional log create as the commit, per collection.
35
+
36
+ <!-- Hero demo: render `docs/assets/demo.gif` from `docs/assets/demo.tape`
37
+ (`vhs docs/assets/demo.tape`) against a real bucket, then uncomment:
38
+ ![baerly-storage in 15 seconds — write a row, then list the bucket](./docs/assets/demo.gif)
39
+ -->
40
40
 
41
41
  ## Quick start
42
42
 
43
43
  ```sh
44
- pnpm create @gusto/baerly-storage@latest -- my-app --target=cloudflare --starter=react
45
- cd my-app && pnpm install && pnpm dev
44
+ pnpm create @gusto/baerly-storage@latest
46
45
  ```
47
46
 
48
- For the Cloudflare target, `pnpm dev` boots Vite + workerd on `:5173`,
49
- so `/v1/*` and the React UI share one origin. No S3 creds are needed
50
- in development.
47
+ The wizard asks for a project name, target, and starter, then prints the
48
+ dev command. First run needs no bucket credentials: local dev uses local
49
+ storage and serves the UI plus `/v1/*` from one origin.
51
50
 
52
- For Node, scaffold with `--target=node --starter=react`; `pnpm dev` also runs on
53
- `:5173` through Vite middleware over `LocalFsStorage`, and production
54
- uses `pnpm start` to run the Node listener anywhere Node runs —
55
- Railway, Render, Fly, Docker, bare VMs, on-prem boxes.
51
+ For a runnable multi-tab demo see
52
+ [`examples/react-node/`](./examples/react-node); for the full set of
53
+ production-shaped scaffolds see [`examples/`](./examples).
54
+
55
+ ## In code
56
+
57
+ The public surface is a small document API. The scaffolds wire `db` on
58
+ the server and `useQuery` in React; the calls look like this:
59
+
60
+ ```ts
61
+ // server — writes land in your object-storage bucket
62
+ await db.collection("tickets").insert({ title: "Onboard Alex", status: "open" });
63
+
64
+ // client — reactive over your trusted handler, across every open tab
65
+ const open = useQuery((c) => c.collection("tickets").where({ status: "open" }).all(), []);
66
+ // open.status → "loading" | "refreshing" | "ok" | "skipped" | "error"
67
+ // open.data is present for "ok" / "refreshing"
68
+ ```
56
69
 
57
- ## The storage backend
70
+ Application auth and tenant choice stay explicit in the handler. What
71
+ disappears is the database service and its surrounding machinery:
58
72
 
59
73
  ```diff
60
74
  - docker-compose.yml
@@ -69,25 +83,15 @@ Railway, Render, Fly, Docker, bare VMs, on-prem boxes.
69
83
  + // baerly.config.ts
70
84
  + export default defineConfig({
71
85
  + app: "tickets",
86
+ + tenant: "main",
72
87
  + collections: { tickets: {} },
73
88
  + target: "cloudflare",
89
+ + auth: "none", // dev; production supplies a verifier
74
90
  + });
75
91
  ```
76
92
 
77
- Your data lives in your bucket. The entire public surface fits in `.d.ts`
78
- files — no DDL, no SQL strings, no generated migration ceremony for
79
- ordinary schema shape changes.
80
-
81
- ## In code
82
-
83
- ```ts
84
- // server — writes land in your R2 bucket
85
- await db.collection("tickets").insert({ title: "Onboard Alex", status: "open" });
86
-
87
- // client — reactive across every open tab
88
- const open = useQuery((c) => c.collection("tickets").where({ status: "open" }).all(), []);
89
- // open.status → "loading" | "ok" | "error"; open.data → your rows
90
- ```
93
+ Ordinary schema shape changes are TypeScript or config edits — no DDL, no
94
+ SQL strings, no generated migration ceremony.
91
95
 
92
96
  ## Cheat sheet
93
97
 
@@ -108,48 +112,109 @@ db.collection("tickets").where({ status: "closed" }).delete();
108
112
  | Surface | Vocabulary |
109
113
  | ------------- | ------------------------------------------------------------------------------------- |
110
114
  | **Verbs** | `first` `all` `count` `get` · `insert` `update` `replace` `delete` |
111
- | **Modifiers** | `where` `order` `limit` |
112
- | **Operators** | `eq` `gt` `gte` `lt` `lte` `in` |
115
+ | **Modifiers** | `where` `order` `limit` |
116
+ | **Operators** | `eq` `gt` `gte` `lt` `lte` `in` |
113
117
  | **Errors** | one `BaerlyError`, discriminate by `.code` (`Conflict`, `NotFound`, `SchemaError`, …) |
114
118
 
115
- Full reference: [`docs/guide/cheatsheet.md`](./docs/guide/cheatsheet.md), or
116
- `cat node_modules/@gusto/baerly-storage/dist/API.md` in an installed app.
117
-
118
- ## Why?
119
-
120
- - **An API an LLM can use first try.** The whole public surface fits in
121
- `.d.ts` files. No DDL. No raw SQL. Discriminated string errors.
122
- Provisioning is `pnpm install`, not a cloud-console detour. The
123
- vocabulary is intentionally small enough to hold in context.
124
- - **Idle rounds to zero.** No $5/mo floors multiplied across forty
125
- abandoned internal tools the loop produced last quarter. There is
126
- no per-app database service bill; the runtime is a rounding error
127
- against the bucket.
128
- - **No hostage situation.** Per-collection snapshot export is shipped:
129
- `baerly export --target=postgres --collection=<name>` dumps a
130
- collection to SQL — run it per collection to hand off a whole app.
131
- Log entries are already a Debezium-style CDC envelope, so an
132
- incremental CDC exit stays mechanical (the shape is fixed; the
133
- incremental exporter itself is future work).
134
- - **Honest about its envelope.** Sized for ~10 GB / tenant,
135
- ~30 writes/min/collection sustained, ~100 collections / tenant.
136
- Crossing any of those is the success signal to graduate.
137
-
138
- For a runnable multi-tab demo see
139
- [`examples/react-node/`](./examples/react-node); for the full set of
140
- production-shaped scaffolds see [`examples/`](./examples).
119
+ Full reference: [`docs/guide/cheatsheet.md`](./docs/guide/cheatsheet.md),
120
+ or `cat node_modules/@gusto/baerly-storage/dist/API.md` in an installed
121
+ app.
122
+
123
+ ## How it works
124
+
125
+ **The hard part of a database-in-a-bucket is the commit.** A bucket can
126
+ store objects; it cannot run a transaction coordinator. So one writer must
127
+ win each race, and every reader must be able to tell what won. [S3's strong consistency][s3-strong] makes object
128
+ storage usable as shared state; conditional writes supply the
129
+ one-writer-wins operation.
130
+
131
+ Concretely, a write drops new immutable objects in the bucket and then
132
+ creates the next numbered log entry for that collection with
133
+ create-if-absent (`If-None-Match: "*"`). Two writers racing the same slot
134
+ cannot both win; the loser reads the winner and retries at the next slot.
135
+ That create _is_ the commit. There is no resident coordinator: each
136
+ request reads bucket state, tries that create, and leaves no required
137
+ process behind. A read follows `current.json` to the snapshot and folds
138
+ the committed log tail into rows.
139
+
140
+ baerly-storage shares the immutable-artifact foundation of table formats
141
+ like Apache Iceberg and Delta Lake, but commits with a narrower step: no
142
+ metadata-pointer swap and no separate coordinator — just that one log
143
+ create. See [prior art and lineage](docs/spec/prior-art.md) for how it
144
+ relates to Iceberg, Delta Lake, Litestream, and Turbopuffer.
145
+
146
+ Each collection has its own ordered log, so **writes are per-collection
147
+ linearizable** — the `If-None-Match` log create linearizes every commit.
148
+ Cross-collection writes are unordered and non-atomic; that boundary is
149
+ part of the contract (see [When (not) to use it](#when-not-to-use-it)).
150
+
151
+ The durable contract is the bucket layout plus the conditional-write
152
+ rules. Another language could speak it by writing the same layout and
153
+ honoring the same rules. See
154
+ [`storage-compatibility.md`](./docs/spec/storage-compatibility.md).
155
+
156
+ [s3-strong]: https://aws.amazon.com/blogs/aws/amazon-s3-update-strong-read-after-write-consistency/
157
+
158
+ ### Security model
159
+
160
+ Bucket credentials never leave the server. Browsers talk only to your
161
+ trusted handler, which authenticates the caller, chooses the tenant
162
+ prefix, and applies the protocol against the bucket. Production recipes
163
+ support Cloudflare Access and JWKS bearer verification; shared-secret
164
+ auth is for service-to-service calls and dev. See
165
+ [`client-auth.md`](./docs/guide/client-auth.md).
166
+
167
+ ## When (not) to use it
168
+
169
+ Before you count rows or price reads, ask one question:
170
+
171
+ > Can the app's most important work be done from one collection?
172
+
173
+ If yes, baerly-storage may fit; then check query shape, atomicity, size,
174
+ and cost. A todo list, a single board's kanban, an event's RSVPs, one
175
+ channel's chat — each maps to one collection. The shape is narrow on
176
+ purpose: production-shaped for small workloads with a specific access
177
+ pattern, not a general-purpose database. If the core screen is a view
178
+ _across_ many collections, users, or tenants ("my pull requests," "all
179
+ code search," a cross-org dashboard), baerly-storage
180
+ should not be the only query engine for it.
181
+
182
+ It is **deliberately not** a few things:
183
+
184
+ - **No SQL, no joins.** Equality + dotted-path predicates, operators
185
+ added one at a time. The small surface is part of the contract.
186
+ - **Not a D1 / Postgres replacement.** Those are graduation targets, not
187
+ competitors — baerly-storage keeps the experiment cheap until you know
188
+ whether it's worth graduating.
189
+ - **Browser-direct multi-writer is out.** Trusted server-side app code is
190
+ the design center.
191
+ - **Realtime is long-poll first.** Polling is always correct; a WebSocket
192
+ tier would be a future opt-in.
193
+
194
+ None of these are apologies — baerly-storage names its envelope so
195
+ graduation is a feature, not a surprise: `baerly export
196
+ --target=postgres` makes the exit mechanical.
197
+ The shape test lives in
198
+ [workload-fit.md](./docs/about/workload-fit.md); the numeric envelope in
199
+ [graduation.md](./docs/about/graduation.md).
141
200
 
142
201
  ## Go deeper
143
202
 
203
+ - ✨ **Why baerly-storage** —
204
+ [`docs/about/why-baerly.md`](./docs/about/why-baerly.md)
144
205
  - 🧭 **How it works** —
145
- [`docs/about/how-it-works.md`](./docs/about/how-it-works.md) (the
146
- plain-language mental model — bucket + one conditional log create)
206
+ [`docs/about/how-it-works.md`](./docs/about/how-it-works.md) (bucket +
207
+ conditional log create)
147
208
  - 🧱 **Product thesis** — [`docs/about/thesis.md`](./docs/about/thesis.md)
148
- - 🏗️ **Architecture** — [`docs/contributing/architecture.md`](./docs/contributing/architecture.md)
209
+ - 🏗️ **Architecture** —
210
+ [`docs/architecture.md`](./docs/architecture.md)
149
211
  - 🔧 **Embed by hand** —
150
- [`packages/server/API.md`](./packages/server/API.md) (the
151
- embed-by-hand + custom-routes recipes — `baerlyNode().fetch` is the
152
- canonical shape; ships as `dist/API.md` in the package)
212
+ [`packages/server/API.md`](./packages/server/API.md) (embed-by-hand +
213
+ custom-routes recipes; ships as `dist/API.md` in the package)
214
+ - 📊 **Alternatives** —
215
+ [`docs/about/alternatives.md`](./docs/about/alternatives.md) (how
216
+ baerly-storage compares to Firebase, Supabase, Convex, and Cloudflare
217
+ D1)
153
218
 
154
219
  ## Where things live
155
220
 
package/dist/API.md CHANGED
@@ -34,6 +34,8 @@ import {
34
34
  MemoryStorage, // in-memory `Storage`; canonical for tests
35
35
  type Collection,
36
36
  type Query,
37
+ type Predicate, // equality-object `.where(...)` form
38
+ type PredicateArg, // `.where(...)` arg: object or builder callback
37
39
  type DocumentData,
38
40
  type RowOf,
39
41
  type CollectionNames, // row-shape inference from a bound config
@@ -59,6 +61,8 @@ import {
59
61
  type ClientQuery,
60
62
  type TerminalOptions,
61
63
  type Fetcher,
64
+ type Predicate,
65
+ type PredicateArg,
62
66
  } from "@gusto/baerly-storage/client";
63
67
 
64
68
  // Auth verifiers
@@ -81,6 +85,8 @@ import { LocalFsStorage } from "@gusto/baerly-storage/dev";
81
85
 
82
86
  ## `Db.create({ storage, app, tenant, config? })`
83
87
 
88
+ *When NOT to use: in a browser/SPA — use `createBaerlyClient` (HTTP) instead; `Db` is the in-process server surface.*
89
+
84
90
  One `Db` per `(app, tenant)` request. The constructor is private —
85
91
  always go through `Db.create`. Collections are auto-provisioned on first
86
92
  write (no `ensureCollection` step).
@@ -141,6 +147,8 @@ overloads as the inferred return; `Db` (no parameter) widens to
141
147
 
142
148
  ## `db.collection(name)` → `Collection<T>`
143
149
 
150
+ *When NOT to use: from the browser — call collection verbs over HTTP via `createBaerlyClient`.*
151
+
144
152
  `Collection<T>` carries the common-case verbs directly (collection-level
145
153
  reads plus by-primary-key mutations). Modifiers (`where`, `order`,
146
154
  `limit`) return a `Query<T>` for bulk-by-predicate work. Terminals fire
@@ -182,7 +190,8 @@ interface Query<T> extends /* Collection<T>'s modifiers */ {
182
190
  `replace` is by-id only — `Collection<T>.replace(id, doc)` throws
183
191
  `NotFound` on missing id. There is no predicate-form `.replace(doc)`
184
192
  on `Query<T>`: a strict-cardinality-1 verb is redundant ceremony to
185
- the by-id form (see ADR-002).
193
+ the by-id form (the public surface is additive-only locked, so a second
194
+ type-valid path to one capability is redundancy).
186
195
 
187
196
  ### Predicates
188
197
 
@@ -330,7 +339,7 @@ try {
330
339
  await db.collection("tickets").insert({ title: "hi" });
331
340
  } catch (err) {
332
341
  if (err instanceof BaerlyError && err.code === "Conflict") {
333
- // CAS lost; caller decides whether to retry
342
+ // Check err.retriable: CAS conflicts can retry; duplicate _id cannot.
334
343
  }
335
344
  }
336
345
  ```
@@ -377,10 +386,16 @@ app.post("/notes", async (c) => {
377
386
  });
378
387
  ```
379
388
 
380
- `mapError` accepts any thrown value — non-`BaerlyError` throws fall
381
- through to `500 Internal` with the message redacted, and the
382
- underlying error is logged via the observability channel. The HTTP
383
- status / envelope shape is locked.
389
+ `mapError` accepts any thrown value. Caller-facing errors such as
390
+ `SchemaError`, `NotFound`, `PayloadTooLarge`, predicate `InvalidConfig`,
391
+ and non-retriable caller `Conflict`s keep their actionable message.
392
+ Storage/server diagnostics such as `Internal`, `NetworkError`,
393
+ `InvalidResponse`, storage `AccessDenied`, storage `InvalidConfig`, and
394
+ retriable CAS/storage `Conflict`s keep their code/status/retriable shape
395
+ but use a generic wire message; the full thrown error is logged via the
396
+ observability channel. Non-`BaerlyError` throws fall through to
397
+ `500 Internal` with the message redacted. The HTTP status / envelope shape
398
+ is locked.
384
399
 
385
400
  ## `defineConfig({ app, tenant, target, collections })`
386
401
 
@@ -416,7 +431,9 @@ Schemas: any [StandardSchema v1](https://standardschema.dev) validator
416
431
  (Zod 3.24+, Valibot 0.36+, ArkType 2.0+). Validation runs on the
417
432
  post-image: `update` and `replace` see the full doc, not just the
418
433
  patch. Failures → `BaerlyError{code:"SchemaError", issues:[…]}`,
419
- mapped to HTTP 400.
434
+ mapped to HTTP 400. Validation is write-path only — reads, export, and
435
+ replay never re-validate, so a schema change never retroactively rejects
436
+ existing rows.
420
437
 
421
438
  **Author `_id` as required, not `.optional()`.** The validator runs
422
439
  on the post-image — by the time it fires, the server has already
@@ -443,6 +460,8 @@ preserved).
443
460
 
444
461
  ## `createBaerlyClient` (browser / Node HTTP client)
445
462
 
463
+ *When NOT to use: server-side in the same process as `Db` — call `Db`/`Collection` directly; the client is for out-of-process / browser callers.*
464
+
446
465
  ```ts
447
466
  import type config from "./baerly.config"; // type-only — server adapter stays out of the SPA bundle
448
467
  const client = createBaerlyClient<typeof config>({
@@ -627,6 +646,16 @@ If your probe path is fixed to something else (a k8s readiness path,
627
646
  say), put a custom route in front of the kernel (see "Recipe — custom
628
647
  routes in front of `baerlyNode`" below).
629
648
 
649
+ ### Machine contract (`GET /v1/spec`)
650
+
651
+ `baerlyWorker` and `baerlyNode` both mount an anonymous
652
+ `GET /v1/spec` → the machine-readable contract IR (error codes +
653
+ HTTP status, predicate operators, method/route tables) — the same
654
+ data shipped as `dist/baerly.spec.json`. It runs the verifier
655
+ tolerantly: an unauthenticated probe gets the static contract (no
656
+ 401), and a request that the verifier accepts additionally gets a
657
+ `collections` array of declared collection + index names.
658
+
630
659
  ### Read modifiers (query params)
631
660
 
632
661
  `GET /v1/c/:collection` accepts three JSON-encoded query params; all are
@@ -647,6 +676,8 @@ client.
647
676
 
648
677
  ## Adapter factories
649
678
 
679
+ *On Cloudflare Workers use `r2BindingStorage(env.BUCKET)` (the R2 binding), NOT the S3-credentials factory — credential-based factories assume `fetch` + Node TLS, not the Workers runtime.*
680
+
650
681
  ```ts
651
682
  // Cloudflare Worker entry
652
683
  import { baerlyWorker } from "@gusto/baerly-storage/cloudflare";
@@ -655,8 +686,18 @@ export default baerlyWorker((env) => ({
655
686
  // scheduled?: (controller, env, ctx) => … // opt-in cron handler
656
687
  }));
657
688
 
658
- // Node listener entry (any host that runs `node server.js`)
659
- import { baerlyNode, s3Storage } from "@gusto/baerly-storage/node";
689
+ // Node listener entry (any host that runs `node server.js`).
690
+ // resolveStorageFromEnv() is the safe default selector: R2_ACCOUNT_ID → R2,
691
+ // BUCKET → S3, else local-fs (dev only). It REFUSES to start in a detected
692
+ // deployment with no bucket — never a silent in-memory/local-fs fallback,
693
+ // which is how hand-rolled selectors ship data loss to production.
694
+ // (assertStorageReachable(storage) adds an opt-in boot-time CAS probe.)
695
+ import { baerlyNode, resolveStorageFromEnv } from "@gusto/baerly-storage/node";
696
+ const { storage, label } = resolveStorageFromEnv();
697
+ baerlyNode({ storage, webRoot: "dist/client" }).listen(PORT); // webRoot optional
698
+
699
+ // Or select the store yourself (custom endpoint, MinIO, GCS, …):
700
+ import { s3Storage } from "@gusto/baerly-storage/node";
660
701
  baerlyNode({
661
702
  storage: s3Storage({ bucket: "…", credentials: { … } }),
662
703
  verifier: bearerJwt({ jwks, issuer, audience }),
@@ -709,12 +750,7 @@ export default baerlyWorker(() => ({ config }));
709
750
  `s3Storage` / `r2Storage` / `minioStorage` / `gcsStorage` from
710
751
  `@gusto/baerly-storage/node` are re-exports of one factory family — same
711
752
  shape (bucket + credentials), all hide `aws4fetch` / `@xmldom/xmldom`
712
- behind the package boundary. **Don't confuse them with
713
- `r2BindingStorage` from `@gusto/baerly-storage/cloudflare`**: that one takes
714
- the platform-bound `R2Bucket` directly (`r2BindingStorage(env.BUCKET)`)
715
- and is the only storage factory a Worker should reach for — the
716
- credential-based factories assume `fetch` + Node TLS, not the Workers
717
- runtime.
753
+ behind the package boundary.
718
754
 
719
755
  ### Verifier presets
720
756
 
@@ -743,8 +779,9 @@ Signature, audience, and expiry checks are still enforced; only
743
779
  tenant derivation is replaced.
744
780
 
745
781
  **Why a function and not a class?** The source repo's
746
- `docs/adr/005-verifier-function-shape.md` records the three
747
- properties the shape upholds and the four rejected alternatives.
782
+ `docs/guide/auth.md` records the properties the shape upholds and the
783
+ rejected alternatives (class hierarchy, middleware chain, closed enum,
784
+ kernel-side composition).
748
785
 
749
786
  ## Observability
750
787
 
@@ -880,13 +917,14 @@ export default {
880
917
 
881
918
  The client reads via the normal `GET /v1/c/messages` route and tails
882
919
  via `GET /v1/since?collection=messages&cursor=…` — both still served by
883
- `inner`. Only writes go through `/api/messages`.
920
+ `inner`. Only writes go through `/api/messages`. Reads stay uncapped and
921
+ tenant-wide — scope and clamp them in your route too (see RECIPES.md).
884
922
 
885
923
  **Known limitations of this recipe.** The custom-route `Db.create` is
886
924
  a second instance — it doesn't share `baerlyWorker`'s
887
925
  `observableStorage(...)` wrapping (so custom-route writes don't land
888
926
  in the canonical-line storage counters) or the read-cache invalidation
889
- helper. For pre-launch chat-shape apps this is acceptable; the
927
+ helper. For small chat-shaped apps this is acceptable; the
890
928
  observability gap is being tracked as a follow-up. If you also need
891
929
  PATCH/PUT/DELETE on the same collection, repeat steps (1) and (2) for
892
930
  each verb.
@@ -1046,22 +1084,16 @@ once. Pick by what you want to observe.
1046
1084
 
1047
1085
  ## Anti-patterns
1048
1086
 
1049
- - Don't reach into `node_modules/@gusto/baerly-storage/dist/` at runtime —
1050
- consume the published exports.
1051
- - Don't widen branded types (`UUID`, `ContentVersionId`) with
1052
- `as string`. The brand exists to prevent confusion bugs.
1053
- - Don't put `SHARED_SECRET` in the SPA bundle. It's
1054
- server-to-server-only; the dev path uses `baerlyDevAuth` to inject
1055
- it server-side, the prod path uses CF Access (CF target) or
1056
- `bearerJwt` (Node target).
1057
- - Don't mutate `VerifierResult.tenantPrefix` between the verifier
1058
- and `Db.create`. The dispatcher pins the tenant from the
1059
- verifier's return value.
1087
+ A few that compile but are wrong (full list, keyed by the exact error
1088
+ string you see: `cat node_modules/@gusto/baerly-storage/dist/RECIPES.md`):
1089
+
1090
+ - Don't widen branded types (`UUID`, `ContentVersionId`) with `as string`.
1091
+ - Don't put `SHARED_SECRET` in the SPA bundle — it's server-to-server only.
1060
1092
 
1061
1093
  ## Where to look next
1062
1094
 
1063
1095
  - **A call you expected doesn't type-check?** The public surface is
1064
- additive-only locked (ADR-002), but the rare breaking change carries an
1096
+ additive-only locked, but the rare breaking change carries an
1065
1097
  old→new migration in `dist/CHANGELOG.md` (`cat dist/CHANGELOG.md`). The
1066
1098
  `.d.ts` types are canonical; the changelog is the recovery path.
1067
1099
  - Per-symbol JSDoc: read the `.d.ts` chunks in this directory
@@ -1069,4 +1101,4 @@ once. Pick by what you want to observe.
1069
1101
  splits them; `cat dist/*.d.ts` gives the union.
1070
1102
  - Theoretical foundations + cost model: the repository's `docs/`
1071
1103
  tree (`docs/about/`, `docs/spec/`).
1072
- - Recipes: `docs/guide/` (auth, observability, backups, troubleshooting).
1104
+ - Common mistakes & recipes: `cat node_modules/@gusto/baerly-storage/dist/RECIPES.md`; deeper guides in the repo's `docs/guide/`.