@gusto/baerly-storage 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. package/README.md +47 -124
  2. package/dist/API.md +161 -511
  3. package/dist/CHANGELOG.md +1148 -307
  4. package/dist/RECIPES.md +398 -80
  5. package/dist/THIRD-PARTY-LICENSES.txt +5 -26
  6. package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
  7. package/dist/app-config.d.ts +31 -1
  8. package/dist/app-config.js +1 -2
  9. package/dist/app-config.js.map +1 -1
  10. package/dist/auth.d.ts +33 -28
  11. package/dist/auth.js +549 -985
  12. package/dist/auth.js.map +1 -1
  13. package/dist/baerly.js +130 -138
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +97 -22
  16. package/dist/capacity-warning-header-BlVopyiI.js +16 -0
  17. package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
  18. package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
  19. package/dist/client-react.d.ts +67 -20
  20. package/dist/client-react.js +240 -54
  21. package/dist/client-react.js.map +1 -1
  22. package/dist/client.d.ts +5 -4
  23. package/dist/client.js +51 -16
  24. package/dist/client.js.map +1 -1
  25. package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
  26. package/dist/cloudflare-CKHYXccw.js.map +1 -0
  27. package/dist/cloudflare.d.ts +106 -71
  28. package/dist/cloudflare.js +334 -271
  29. package/dist/cloudflare.js.map +1 -1
  30. package/dist/code-resolution-CL_7L0wS.js +22 -0
  31. package/dist/code-resolution-CL_7L0wS.js.map +1 -0
  32. package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
  33. package/dist/config-DEzInG6M.js +4035 -0
  34. package/dist/config-DEzInG6M.js.map +1 -0
  35. package/dist/constants-D3GSH3tc.js +469 -0
  36. package/dist/constants-D3GSH3tc.js.map +1 -0
  37. package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
  38. package/dist/context-rlpSnHFA.js.map +1 -0
  39. package/dist/cost-B52llVDx.js +330 -0
  40. package/dist/cost-B52llVDx.js.map +1 -0
  41. package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
  42. package/dist/current-json-CC6lE4Aj.js.map +1 -0
  43. package/dist/db-plFUNTSF.d.ts +130 -0
  44. package/dist/db-read-seams-BSs0m1z1.js +3261 -0
  45. package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
  46. package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
  47. package/dist/deploy-Obj4nE-Z.js.map +1 -0
  48. package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
  49. package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
  50. package/dist/dev-landing-CD-si4dW.js +50 -0
  51. package/dist/dev-landing-CD-si4dW.js.map +1 -0
  52. package/dist/dev-vite.d.ts +38 -39
  53. package/dist/dev-vite.js +67 -36
  54. package/dist/dev-vite.js.map +1 -1
  55. package/dist/dev.d.ts +3 -2
  56. package/dist/dev.js +2 -1
  57. package/dist/doctor-BA0i-YAN.js +270 -0
  58. package/dist/doctor-BA0i-YAN.js.map +1 -0
  59. package/dist/dump-D1vX8ozg.js +133 -0
  60. package/dist/dump-D1vX8ozg.js.map +1 -0
  61. package/dist/errors-7Rk1HGCE.js +160 -0
  62. package/dist/errors-7Rk1HGCE.js.map +1 -0
  63. package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
  64. package/dist/export-BVL2EvYE.js.map +1 -0
  65. package/dist/fsck-BWkPgov4.js +145 -0
  66. package/dist/fsck-BWkPgov4.js.map +1 -0
  67. package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
  68. package/dist/gcs.d.ts +30 -0
  69. package/dist/gcs.js +1 -0
  70. package/dist/goog4-signer-CeLIABoE.js +331 -0
  71. package/dist/goog4-signer-CeLIABoE.js.map +1 -0
  72. package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
  73. package/dist/http-Z5rZyYMX.js.map +1 -0
  74. package/dist/http-transport-DNUM8kU-.js +1299 -0
  75. package/dist/http-transport-DNUM8kU-.js.map +1 -0
  76. package/dist/http.d.ts +366 -294
  77. package/dist/http.js +2 -2
  78. package/dist/index-JJrIu1pO.d.ts +135 -0
  79. package/dist/index-LEgHN0qJ.d.ts +50 -0
  80. package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
  81. package/dist/index.d.ts +27 -6
  82. package/dist/index.js +3 -5
  83. package/dist/inspect-BTsVYZKd.js +196 -0
  84. package/dist/inspect-BTsVYZKd.js.map +1 -0
  85. package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
  86. package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
  87. package/dist/ledger-Dj_bGgo0.js +192 -0
  88. package/dist/ledger-Dj_bGgo0.js.map +1 -0
  89. package/dist/legacy-names-DgZBtgOh.js +47 -0
  90. package/dist/legacy-names-DgZBtgOh.js.map +1 -0
  91. package/dist/log-C9W15Dfo.d.ts +94 -0
  92. package/dist/log-tail-DWJbneBF.js +142 -0
  93. package/dist/log-tail-DWJbneBF.js.map +1 -0
  94. package/dist/log-walk-C-vA-WGJ.js +111 -0
  95. package/dist/log-walk-C-vA-WGJ.js.map +1 -0
  96. package/dist/maintenance-Dd-Yakqj.js +1709 -0
  97. package/dist/maintenance-Dd-Yakqj.js.map +1 -0
  98. package/dist/maintenance-DevB6z4e.js +2237 -0
  99. package/dist/maintenance-DevB6z4e.js.map +1 -0
  100. package/dist/maintenance.d.ts +100 -3
  101. package/dist/maintenance.js +1 -3
  102. package/dist/node.d.ts +130 -142
  103. package/dist/node.js +4 -3
  104. package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
  105. package/dist/observability-C-ISCCLE.js.map +1 -0
  106. package/dist/observability.d.ts +27 -3
  107. package/dist/observability.js +3 -3
  108. package/dist/path-segment-DBXG26PW.js +363 -0
  109. package/dist/path-segment-DBXG26PW.js.map +1 -0
  110. package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
  111. package/dist/plan-BvQbaNMe.js.map +1 -0
  112. package/dist/request-CRWiTrza.js +272 -0
  113. package/dist/request-CRWiTrza.js.map +1 -0
  114. package/dist/restore-U6Im8V1V.js +1467 -0
  115. package/dist/restore-U6Im8V1V.js.map +1 -0
  116. package/dist/retry-OBtLB2GC.js +126 -0
  117. package/dist/retry-OBtLB2GC.js.map +1 -0
  118. package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
  119. package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
  120. package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
  121. package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
  122. package/dist/s3.d.ts +20 -7
  123. package/dist/s3.js +4 -5
  124. package/dist/s3.js.map +1 -1
  125. package/dist/sha256-4FfGQNPw.js +22 -0
  126. package/dist/sha256-4FfGQNPw.js.map +1 -0
  127. package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
  128. package/dist/shared-secret-Vkur-8r0.js.map +1 -0
  129. package/dist/sigv4-sign-5IUflUD_.js +507 -0
  130. package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
  131. package/dist/snapshot-CknzkDM0.js +148 -0
  132. package/dist/snapshot-CknzkDM0.js.map +1 -0
  133. package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
  134. package/dist/src-Actga-bO.js.map +1 -0
  135. package/dist/src-D0MQfvOp.js +812 -0
  136. package/dist/src-D0MQfvOp.js.map +1 -0
  137. package/dist/src-Dr9uo3dc.js +501 -0
  138. package/dist/src-Dr9uo3dc.js.map +1 -0
  139. package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
  140. package/dist/subcommand-BLoF66dG.js.map +1 -0
  141. package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
  142. package/dist/time-DRxTP9iv.js.map +1 -0
  143. package/dist/types-suVbsEWS.d.ts +116 -0
  144. package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
  145. package/dist/usage-CPzVhrQr.js.map +1 -0
  146. package/dist/uuid-BuT_c404.js +333 -0
  147. package/dist/uuid-BuT_c404.js.map +1 -0
  148. package/dist/verifier-Bmlmndzo.d.ts +95 -0
  149. package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
  150. package/dist/wire-DndvKU-K.js.map +1 -0
  151. package/package.json +96 -69
  152. package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
  153. package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
  154. package/dist/bytes-BXdamO3L.js +0 -11
  155. package/dist/bytes-BXdamO3L.js.map +0 -1
  156. package/dist/cloudflare-DzKBrUlg.js.map +0 -1
  157. package/dist/config-1tv0-Yzm.js +0 -2693
  158. package/dist/config-1tv0-Yzm.js.map +0 -1
  159. package/dist/constants-CfeMWQWk.js +0 -222
  160. package/dist/constants-CfeMWQWk.js.map +0 -1
  161. package/dist/context-DRZ3tZ5l.js.map +0 -1
  162. package/dist/cost-DSMIVqzL.js +0 -203
  163. package/dist/cost-DSMIVqzL.js.map +0 -1
  164. package/dist/current-json-C6nhPOm1.js.map +0 -1
  165. package/dist/db-DsPkOVEH.d.ts +0 -254
  166. package/dist/deploy-DonTr-CV.js.map +0 -1
  167. package/dist/doctor-DSIyCDg_.js +0 -346
  168. package/dist/doctor-DSIyCDg_.js.map +0 -1
  169. package/dist/dump-Bh5k26VQ.js +0 -94
  170. package/dist/dump-Bh5k26VQ.js.map +0 -1
  171. package/dist/errors-Dfa3p78c.js +0 -78
  172. package/dist/errors-Dfa3p78c.js.map +0 -1
  173. package/dist/export-DtF5tDIM.js +0 -401
  174. package/dist/export-DtF5tDIM.js.map +0 -1
  175. package/dist/fsck-D_djMO5D.js +0 -279
  176. package/dist/fsck-D_djMO5D.js.map +0 -1
  177. package/dist/http-DGd5tbNs.js.map +0 -1
  178. package/dist/index-0rZcMBwy.d.ts +0 -115
  179. package/dist/index-BNRh23K9.d.ts +0 -162
  180. package/dist/index-BYk9oCNf.d.ts +0 -1112
  181. package/dist/indexes-Dn9hbGQG.d.ts +0 -22
  182. package/dist/inspect-6WZ-pC7-.js +0 -133
  183. package/dist/inspect-6WZ-pC7-.js.map +0 -1
  184. package/dist/log-tail-D98U1JBo.js +0 -522
  185. package/dist/log-tail-D98U1JBo.js.map +0 -1
  186. package/dist/maintenance-B4Dki6Ig.js +0 -2157
  187. package/dist/maintenance-B4Dki6Ig.js.map +0 -1
  188. package/dist/maintenance-B_e0T99L.d.ts +0 -537
  189. package/dist/maintenance-C7coQp4c.js +0 -1418
  190. package/dist/maintenance-C7coQp4c.js.map +0 -1
  191. package/dist/normalize-rjnZLwS4.js +0 -133
  192. package/dist/normalize-rjnZLwS4.js.map +0 -1
  193. package/dist/observability-BmflLCdF.js.map +0 -1
  194. package/dist/plan-a7PJHBCy.js.map +0 -1
  195. package/dist/query-rAtXNQQB.js +0 -1773
  196. package/dist/query-rAtXNQQB.js.map +0 -1
  197. package/dist/rebuild-index-BVzQSZlm.js +0 -81
  198. package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
  199. package/dist/request-u0M51mhJ.js +0 -72
  200. package/dist/request-u0M51mhJ.js.map +0 -1
  201. package/dist/restore-R-4rbciV.js +0 -778
  202. package/dist/restore-R-4rbciV.js.map +0 -1
  203. package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
  204. package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
  205. package/dist/shared-secret-DgEicd3x.js.map +0 -1
  206. package/dist/src-BL_JoPTn.js.map +0 -1
  207. package/dist/src-CYHFDrKz.js +0 -536
  208. package/dist/src-CYHFDrKz.js.map +0 -1
  209. package/dist/src-DYZ4H1aF.js +0 -392
  210. package/dist/src-DYZ4H1aF.js.map +0 -1
  211. package/dist/subcommand-DoDA-K7d.js.map +0 -1
  212. package/dist/time-DUqvFMHq.js.map +0 -1
  213. package/dist/usage-DBV1eQHC.js.map +0 -1
  214. package/dist/validate-DtljsCh1.js.map +0 -1
  215. package/dist/wire-izfGZDvr.js.map +0 -1
package/README.md CHANGED
@@ -9,29 +9,16 @@ before: client → app handler → database server (a server)
9
9
  after: client → app handler → S3/R2 bucket (just storage)
10
10
  ```
11
11
 
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.
12
+ The trick is to cram the entire database execution layer inside an HTTP request. There is no server, daemon, or coordinator: each read or write runs as library code inside your request handler, the bucket holds the data, and the protocol supplies the commit rules.
13
+
14
+ The load-bearing operation is narrow — one conditional create of the next log object commits a write. When the request ends, baerly-storage is gone. Poof!
15
+
16
+ - **An API small enough to hold in your context.** No DDL, no raw SQL — 8 verbs and a ~12k-token surface you can hand to an LLM or a non-engineer and walk away.
17
+ - **Idle rounds to zero.** No database process to keep warm, and no per-app database floor across a fleet of small internal tools.
18
+ - **No data hostage.** `baerly export --target=postgres` gives you a per-collection SQL snapshot. Crossing the envelope is the graduation signal; the data exit is mechanical.
19
+ - **No new vendor.** Your S3/R2 bucket cleared security review years ago; every hosted alternative means a fresh vendor review and an IT ticket for a new managed-DB SKU.
20
+ - **Nothing to go down.** No resident service in your critical path, one fewer failure domain. Servers that don't exist can't go down.
21
+ - **Built like git.** Content-addressed snapshots, immutable numbered log entries, and one conditional log create as the commit, per collection.
35
22
 
36
23
  <!-- Hero demo: render `docs/assets/demo.gif` from `docs/assets/demo.tape`
37
24
  (`vhs docs/assets/demo.tape`) against a real bucket, then uncomment:
@@ -44,18 +31,13 @@ log object commits a write. When the request ends, baerly-storage is gone. Poof!
44
31
  pnpm create @gusto/baerly-storage@latest
45
32
  ```
46
33
 
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.
34
+ The wizard asks for a project name, target, and starter, then prints the dev command. First run needs no bucket credentials: local dev uses local storage and serves the UI plus `/v1/*` from one origin.
50
35
 
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).
36
+ For a runnable multi-tab demo see [`examples/react-node/`](./examples/react-node); for the full set of production-shaped scaffolds see [`examples/`](./examples).
54
37
 
55
38
  ## In code
56
39
 
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:
40
+ The public surface is a small document API. The scaffolds wire `db` on the server and `useQuery` in React; the calls look like this:
59
41
 
60
42
  ```ts
61
43
  // server — writes land in your object-storage bucket
@@ -67,8 +49,7 @@ const open = useQuery((c) => c.collection("tickets").where({ status: "open" }).a
67
49
  // open.data is present for "ok" / "refreshing"
68
50
  ```
69
51
 
70
- Application auth and tenant choice stay explicit in the handler. What
71
- disappears is the database service and its surrounding machinery:
52
+ Application auth and tenant choice stay explicit in the handler. What disappears is the database service and its surrounding machinery:
72
53
 
73
54
  ```diff
74
55
  - docker-compose.yml
@@ -90,8 +71,7 @@ disappears is the database service and its surrounding machinery:
90
71
  + });
91
72
  ```
92
73
 
93
- Ordinary schema shape changes are TypeScript or config edits — no DDL, no
94
- SQL strings, no generated migration ceremony.
74
+ Ordinary schema shape changes are TypeScript or config edits — no DDL, no SQL strings, no generated migration ceremony.
95
75
 
96
76
  ## Cheat sheet
97
77
 
@@ -109,60 +89,32 @@ db.collection("tickets").update(id, { status: "closed" }); // merge-patch
109
89
  db.collection("tickets").where({ status: "closed" }).delete();
110
90
  ```
111
91
 
112
- | Surface | Vocabulary |
113
- | ------------- | ------------------------------------------------------------------------------------- |
114
- | **Verbs** | `first` `all` `count` `get` · `insert` `update` `replace` `delete` |
115
- | **Modifiers** | `where` `order` `limit` |
116
- | **Operators** | `eq` `gt` `gte` `lt` `lte` `in` |
117
- | **Errors** | one `BaerlyError`, discriminate by `.code` (`Conflict`, `NotFound`, `SchemaError`, …) |
92
+ | Surface | Vocabulary |
93
+ | --- | --- |
94
+ | **Verbs** | `first` `all` `count` `get` · `insert` `update` `replace` `delete` |
95
+ | **Modifiers** | `where` `order` `limit` |
96
+ | **Operators** | `eq` `gt` `gte` `lt` `lte` `in` |
97
+ | **Errors** | one `BaerlyError`, discriminate by `.code` (`WriteConflict`, `NotFound`, `SchemaError`, …) |
118
98
 
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.
99
+ Full reference: [`docs/guide/cheatsheet.md`](./docs/guide/cheatsheet.md), or `cat node_modules/@gusto/baerly-storage/dist/API.md` in an installed app.
122
100
 
123
101
  ## How it works
124
102
 
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).
103
+ **The hard part of a database-in-a-bucket is the commit.** A bucket can store objects; it cannot run a transaction coordinator. So one writer must win each race, and every reader must be able to tell what won. [S3's strong consistency][s3-strong] makes object storage usable as shared state; conditional writes supply the one-writer-wins operation.
104
+
105
+ Concretely, a write drops new immutable objects in the bucket and then creates the next numbered log entry for that collection with create-if-absent (`If-None-Match: "*"`). Two writers racing the same slot cannot both win; the loser reads the winner and retries at the next slot. That create _is_ the commit. There is no resident coordinator: each request reads bucket state, tries that create, and leaves no required process behind. A read follows `current.json` to the snapshot and folds the committed log tail into rows.
106
+
107
+ baerly-storage shares the immutable-artifact foundation of table formats like Apache Iceberg and Delta Lake, but commits with a narrower step: no metadata-pointer swap and no separate coordinator — just that one log create. See [prior art and lineage](docs/spec/prior-art.md) for how it relates to Iceberg, Delta Lake, Litestream, and Turbopuffer.
108
+
109
+ Each collection has its own ordered log, so **writes are per-collection linearizable** — the `If-None-Match` log create linearizes every commit. Cross-collection writes are unordered and non-atomic; that boundary is part of the contract (see [When (not) to use it](#when-not-to-use-it)).
110
+
111
+ The durable contract is the bucket layout plus the conditional-write rules. Another language could speak it by writing the same layout and honoring the same rules. See [`storage-compatibility.md`](./docs/spec/storage-compatibility.md).
155
112
 
156
113
  [s3-strong]: https://aws.amazon.com/blogs/aws/amazon-s3-update-strong-read-after-write-consistency/
157
114
 
158
115
  ### Security model
159
116
 
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).
117
+ Bucket credentials never leave the server. Browsers talk only to your trusted handler, which authenticates the caller, chooses the tenant prefix, and applies the protocol against the bucket. Production recipes support Cloudflare Access and JWKS bearer verification; shared-secret auth is for service-to-service calls and dev. See [`client-auth.md`](./docs/guide/client-auth.md).
166
118
 
167
119
  ## When (not) to use it
168
120
 
@@ -170,60 +122,31 @@ Before you count rows or price reads, ask one question:
170
122
 
171
123
  > Can the app's most important work be done from one collection?
172
124
 
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.
125
+ If yes, baerly-storage may fit; then check query shape, atomicity, size, and cost. A todo list, a single board's kanban, an event's RSVPs, one channel's chat — each maps to one collection. The shape is narrow on purpose: production-shaped for small workloads with a specific access pattern, not a general-purpose database. If the core screen is a view _across_ many collections, users, or tenants ("my pull requests," "all code search," a cross-org dashboard), baerly-storage should not be the only query engine for it.
181
126
 
182
127
  It is **deliberately not** a few things:
183
128
 
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).
129
+ - **No SQL, no joins.** Equality + dotted-path predicates, operators added one at a time. The small surface is part of the contract.
130
+ - **Not a D1 / Postgres replacement.** Those are graduation targets, not competitors — baerly-storage keeps the experiment cheap until you know whether it's worth graduating.
131
+ - **Browser-direct multi-writer is out.** Trusted server-side app code is the design center.
132
+ - **Realtime is long-poll first.** Polling is always correct; a WebSocket tier would be a future opt-in.
133
+
134
+ None of these are apologies — baerly-storage names its envelope so graduation is a feature, not a surprise: `baerly export --target=postgres` makes the exit mechanical. The shape test lives in [workload-fit.md](./docs/about/workload-fit.md); the numeric envelope in [graduation.md](./docs/about/graduation.md).
200
135
 
201
136
  ## Go deeper
202
137
 
203
- - ✨ **Why baerly-storage** —
204
- [`docs/about/why-baerly.md`](./docs/about/why-baerly.md)
205
- - 🧭 **How it works** —
206
- [`docs/about/how-it-works.md`](./docs/about/how-it-works.md) (bucket +
207
- conditional log create)
138
+ - ✨ **Why baerly-storage** — [`docs/about/why-baerly.md`](./docs/about/why-baerly.md)
139
+ - 🧭 **How it works** — [`docs/about/how-it-works.md`](./docs/about/how-it-works.md) (bucket + conditional log create)
208
140
  - 🧱 **Product thesis** — [`docs/about/thesis.md`](./docs/about/thesis.md)
209
- - 🏗️ **Architecture** —
210
- [`docs/architecture.md`](./docs/architecture.md)
211
- - 🔧 **Embed by hand** —
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)
141
+ - 🏗️ **Architecture** — [`docs/architecture.md`](./docs/architecture.md)
142
+ - 🔧 **Embed by hand** — [`packages/server/API.md`](./packages/server/API.md) (embed-by-hand + custom-routes recipes; ships as `dist/API.md` in the package)
143
+ - 📊 **Alternatives** — [`docs/about/alternatives.md`](./docs/about/alternatives.md) (how baerly-storage compares to Firebase, Supabase, Convex, and Cloudflare D1)
218
144
 
219
145
  ## Where things live
220
146
 
221
- - [`CLAUDE.md`](./CLAUDE.md) — agent + contributor entry point (the
222
- fastest map for humans too). `AGENTS.md` is a symlink.
223
- - [`docs/README.md`](./docs/README.md) — topic map: architecture,
224
- conventions, ADRs, protocol specs, operating procedures.
225
- - [`examples/`](./examples) — runnable scaffolds + the `react-node/`
226
- multi-tab demo.
147
+ - [`CLAUDE.md`](./CLAUDE.md) — agent + contributor entry point (the fastest map for humans too). `AGENTS.md` is a symlink.
148
+ - [`docs/README.md`](./docs/README.md) — topic map: architecture, conventions, ADRs, protocol specs, operating procedures.
149
+ - [`examples/`](./examples) — runnable scaffolds + the `react-node/` multi-tab demo.
227
150
 
228
151
  ## License
229
152