@quickback-dev/cli 0.72.9 → 0.72.11

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 (212) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +8 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/db-explain.d.ts +67 -0
  5. package/dist/commands/db-explain.d.ts.map +1 -0
  6. package/dist/commands/db-explain.js +141 -0
  7. package/dist/commands/db-explain.js.map +1 -0
  8. package/dist/commands/db-export.d.ts +34 -0
  9. package/dist/commands/db-export.d.ts.map +1 -0
  10. package/dist/commands/db-export.js +250 -0
  11. package/dist/commands/db-export.js.map +1 -0
  12. package/dist/commands/db-insights.d.ts +60 -0
  13. package/dist/commands/db-insights.d.ts.map +1 -0
  14. package/dist/commands/db-insights.js +106 -0
  15. package/dist/commands/db-insights.js.map +1 -0
  16. package/dist/commands/db-recovery.d.ts +98 -0
  17. package/dist/commands/db-recovery.d.ts.map +1 -0
  18. package/dist/commands/db-recovery.js +558 -0
  19. package/dist/commands/db-recovery.js.map +1 -0
  20. package/dist/commands/db-target.d.ts +27 -0
  21. package/dist/commands/db-target.d.ts.map +1 -0
  22. package/dist/commands/db-target.js +83 -0
  23. package/dist/commands/db-target.js.map +1 -0
  24. package/dist/commands/db.d.ts +3 -0
  25. package/dist/commands/db.d.ts.map +1 -0
  26. package/dist/commands/db.js +43 -0
  27. package/dist/commands/db.js.map +1 -0
  28. package/dist/commands/effects.d.ts +8 -0
  29. package/dist/commands/effects.d.ts.map +1 -0
  30. package/dist/commands/effects.js +48 -0
  31. package/dist/commands/effects.js.map +1 -0
  32. package/dist/commands/platform-budget.d.ts +143 -0
  33. package/dist/commands/platform-budget.d.ts.map +1 -0
  34. package/dist/commands/platform-budget.js +619 -0
  35. package/dist/commands/platform-budget.js.map +1 -0
  36. package/dist/commands/preview.d.ts +57 -0
  37. package/dist/commands/preview.d.ts.map +1 -0
  38. package/dist/commands/preview.js +268 -0
  39. package/dist/commands/preview.js.map +1 -0
  40. package/dist/commands/search.d.ts +20 -0
  41. package/dist/commands/search.d.ts.map +1 -0
  42. package/dist/commands/search.js +133 -0
  43. package/dist/commands/search.js.map +1 -0
  44. package/dist/index.js +35 -1
  45. package/dist/index.js.map +1 -1
  46. package/dist/lib/api-client.d.ts +4 -0
  47. package/dist/lib/api-client.d.ts.map +1 -1
  48. package/dist/lib/api-client.js.map +1 -1
  49. package/dist/lib/cloudflare-spend-policies.d.ts +92 -0
  50. package/dist/lib/cloudflare-spend-policies.d.ts.map +1 -0
  51. package/dist/lib/cloudflare-spend-policies.js +289 -0
  52. package/dist/lib/cloudflare-spend-policies.js.map +1 -0
  53. package/dist/lib/compiler-stubs.d.ts +2 -0
  54. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  55. package/dist/lib/compiler-stubs.js +2 -0
  56. package/dist/lib/compiler-stubs.js.map +1 -1
  57. package/dist/lib/d1-fingerprint.d.ts +8 -0
  58. package/dist/lib/d1-fingerprint.d.ts.map +1 -0
  59. package/dist/lib/d1-fingerprint.js +113 -0
  60. package/dist/lib/d1-fingerprint.js.map +1 -0
  61. package/dist/lib/file-loader.d.ts +12 -0
  62. package/dist/lib/file-loader.d.ts.map +1 -1
  63. package/dist/lib/file-loader.js +27 -1
  64. package/dist/lib/file-loader.js.map +1 -1
  65. package/dist/lib/migrations/plan.js +3 -0
  66. package/dist/lib/migrations/plan.js.map +1 -1
  67. package/dist/lib/migrations/postprocessors/index.d.ts +6 -5
  68. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
  69. package/dist/lib/migrations/postprocessors/index.js +24 -12
  70. package/dist/lib/migrations/postprocessors/index.js.map +1 -1
  71. package/dist/lib/migrations/postprocessors/search.d.ts +49 -0
  72. package/dist/lib/migrations/postprocessors/search.d.ts.map +1 -0
  73. package/dist/lib/migrations/postprocessors/search.js +160 -0
  74. package/dist/lib/migrations/postprocessors/search.js.map +1 -0
  75. package/dist/lib/migrations/prior-state.d.ts +7 -0
  76. package/dist/lib/migrations/prior-state.d.ts.map +1 -1
  77. package/dist/lib/migrations/prior-state.js +3 -0
  78. package/dist/lib/migrations/prior-state.js.map +1 -1
  79. package/dist/lib/migrations/types.d.ts +1 -1
  80. package/dist/lib/migrations/types.d.ts.map +1 -1
  81. package/dist/lib/migrations/types.js +1 -0
  82. package/dist/lib/migrations/types.js.map +1 -1
  83. package/dist/lib/preview-lifecycle.d.ts +139 -0
  84. package/dist/lib/preview-lifecycle.d.ts.map +1 -0
  85. package/dist/lib/preview-lifecycle.js +429 -0
  86. package/dist/lib/preview-lifecycle.js.map +1 -0
  87. package/dist/lib/preview.d.ts +146 -0
  88. package/dist/lib/preview.d.ts.map +1 -0
  89. package/dist/lib/preview.js +417 -0
  90. package/dist/lib/preview.js.map +1 -0
  91. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  92. package/dist/lib/wrangler-resources.js +4 -2
  93. package/dist/lib/wrangler-resources.js.map +1 -1
  94. package/dist/skill/SKILL.md +9 -3
  95. package/dist/skill/agents/quickback-specialist/AGENT.md +9 -11
  96. package/dist/skill/docs/api/batch-operations.md +19 -0
  97. package/dist/skill/docs/api/caching.md +17 -0
  98. package/dist/skill/docs/api/crud.md +9 -0
  99. package/dist/skill/docs/api/errors.md +31 -2
  100. package/dist/skill/docs/api/query-params.md +6 -0
  101. package/dist/skill/docs/changelog/index.md +1 -0
  102. package/dist/skill/docs/configure/agents.md +1 -1
  103. package/dist/skill/docs/configure/bindings.md +177 -1
  104. package/dist/skill/docs/configure/cloudflare-access.md +43 -0
  105. package/dist/skill/docs/configure/domains.md +1 -1
  106. package/dist/skill/docs/configure/providers.md +5 -0
  107. package/dist/skill/docs/configure/tenant-databases.md +627 -14
  108. package/dist/skill/docs/define/access.md +26 -0
  109. package/dist/skill/docs/define/actions/defining.md +7 -1
  110. package/dist/skill/docs/define/actions/index.md +5 -0
  111. package/dist/skill/docs/define/actions/scoped-db.md +127 -1
  112. package/dist/skill/docs/define/authoring-basics.md +92 -0
  113. package/dist/skill/docs/define/changesets.md +8 -0
  114. package/dist/skill/docs/define/encryption.md +48 -2
  115. package/dist/skill/docs/define/feature.md +17 -2
  116. package/dist/skill/docs/define/guards.md +11 -3
  117. package/dist/skill/docs/define/index.md +1 -1
  118. package/dist/skill/docs/define/invariants.md +321 -0
  119. package/dist/skill/docs/define/issue-tracker-example.md +225 -0
  120. package/dist/skill/docs/define/masking.md +3 -3
  121. package/dist/skill/docs/define/rate-limit.md +78 -30
  122. package/dist/skill/docs/define/read.md +332 -5
  123. package/dist/skill/docs/define/relationships.md +10 -0
  124. package/dist/skill/docs/define/schema.md +137 -10
  125. package/dist/skill/docs/define/scopes.md +1 -0
  126. package/dist/skill/docs/define/transitions.md +9 -0
  127. package/dist/skill/docs/define/triggers.md +127 -1
  128. package/dist/skill/docs/platform/api-contract/index.md +35 -4
  129. package/dist/skill/docs/platform/auth/api-keys.md +26 -3
  130. package/dist/skill/docs/platform/auth/index.md +5 -2
  131. package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
  132. package/dist/skill/docs/platform/database/d1.md +73 -1
  133. package/dist/skill/docs/platform/database/durable-effects.md +224 -0
  134. package/dist/skill/docs/platform/database/neon.md +8 -5
  135. package/dist/skill/docs/platform/database/read-replication.md +9 -0
  136. package/dist/skill/docs/platform/database/recovery.md +292 -0
  137. package/dist/skill/docs/platform/database/using-d1.md +152 -2
  138. package/dist/skill/docs/platform/index.md +1 -0
  139. package/dist/skill/docs/platform/operations/budgets.md +224 -0
  140. package/dist/skill/docs/platform/queues/handlers.md +1 -0
  141. package/dist/skill/docs/platform/queues/index.md +18 -0
  142. package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
  143. package/dist/skill/docs/platform/storage/using-r2.md +13 -0
  144. package/dist/skill/docs/platform/vector/embeddings.md +28 -4
  145. package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
  146. package/dist/skill/docs/platform/workflows/index.md +385 -0
  147. package/dist/skill/docs/start/deploy-browser.md +51 -0
  148. package/dist/skill/docs/start/deploy.md +97 -1
  149. package/dist/skill/docs/tooling/cli.md +117 -0
  150. package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
  151. package/dist/skill/docs/ui/account/customization.md +4 -0
  152. package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
  153. package/package.json +1 -1
  154. package/src/skill/SKILL.md +9 -3
  155. package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
  156. package/src/skill/docs/api/batch-operations.md +19 -0
  157. package/src/skill/docs/api/caching.md +17 -0
  158. package/src/skill/docs/api/crud.md +9 -0
  159. package/src/skill/docs/api/errors.md +31 -2
  160. package/src/skill/docs/api/query-params.md +6 -0
  161. package/src/skill/docs/changelog/index.md +1 -0
  162. package/src/skill/docs/configure/agents.md +1 -1
  163. package/src/skill/docs/configure/bindings.md +177 -1
  164. package/src/skill/docs/configure/cloudflare-access.md +43 -0
  165. package/src/skill/docs/configure/domains.md +1 -1
  166. package/src/skill/docs/configure/providers.md +5 -0
  167. package/src/skill/docs/configure/tenant-databases.md +627 -14
  168. package/src/skill/docs/define/access.md +26 -0
  169. package/src/skill/docs/define/actions/defining.md +7 -1
  170. package/src/skill/docs/define/actions/index.md +5 -0
  171. package/src/skill/docs/define/actions/scoped-db.md +127 -1
  172. package/src/skill/docs/define/authoring-basics.md +92 -0
  173. package/src/skill/docs/define/changesets.md +8 -0
  174. package/src/skill/docs/define/encryption.md +48 -2
  175. package/src/skill/docs/define/feature.md +17 -2
  176. package/src/skill/docs/define/guards.md +11 -3
  177. package/src/skill/docs/define/index.md +1 -1
  178. package/src/skill/docs/define/invariants.md +321 -0
  179. package/src/skill/docs/define/issue-tracker-example.md +225 -0
  180. package/src/skill/docs/define/masking.md +3 -3
  181. package/src/skill/docs/define/rate-limit.md +78 -30
  182. package/src/skill/docs/define/read.md +332 -5
  183. package/src/skill/docs/define/relationships.md +10 -0
  184. package/src/skill/docs/define/schema.md +137 -10
  185. package/src/skill/docs/define/scopes.md +1 -0
  186. package/src/skill/docs/define/transitions.md +9 -0
  187. package/src/skill/docs/define/triggers.md +127 -1
  188. package/src/skill/docs/platform/api-contract/index.md +35 -4
  189. package/src/skill/docs/platform/auth/api-keys.md +26 -3
  190. package/src/skill/docs/platform/auth/index.md +5 -2
  191. package/src/skill/docs/platform/auth/plugins/index.md +1 -1
  192. package/src/skill/docs/platform/database/d1.md +73 -1
  193. package/src/skill/docs/platform/database/durable-effects.md +224 -0
  194. package/src/skill/docs/platform/database/neon.md +8 -5
  195. package/src/skill/docs/platform/database/read-replication.md +9 -0
  196. package/src/skill/docs/platform/database/recovery.md +292 -0
  197. package/src/skill/docs/platform/database/using-d1.md +152 -2
  198. package/src/skill/docs/platform/index.md +1 -0
  199. package/src/skill/docs/platform/operations/budgets.md +224 -0
  200. package/src/skill/docs/platform/queues/handlers.md +1 -0
  201. package/src/skill/docs/platform/queues/index.md +18 -0
  202. package/src/skill/docs/platform/realtime/table-changes.md +1 -0
  203. package/src/skill/docs/platform/storage/using-r2.md +13 -0
  204. package/src/skill/docs/platform/vector/embeddings.md +28 -4
  205. package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
  206. package/src/skill/docs/platform/workflows/index.md +385 -0
  207. package/src/skill/docs/start/deploy-browser.md +51 -0
  208. package/src/skill/docs/start/deploy.md +97 -1
  209. package/src/skill/docs/tooling/cli.md +117 -0
  210. package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
  211. package/src/skill/docs/ui/account/customization.md +4 -0
  212. package/src/skill/docs/ui/admin/record-layouts.md +3 -3
@@ -1,10 +1,10 @@
1
- # Rate Limit - Per-Operation Request Caps
1
+ # Rate Limit - Weighted Requests and Shared Buckets
2
2
 
3
- Per-operation request caps for every CRUD endpoint. Backed by Cloudflare's native [Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) — no extra storage, no third-party libraries.
3
+ Approximate request throttling for CRUD endpoints and actions, with optional static weights and explicitly shared buckets. Backed by Cloudflare's native [Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) — no extra storage, no third-party libraries.
4
4
 
5
5
  ## Defaults
6
6
 
7
- Every resource gets these limits automatically (per authenticated user, per minute):
7
+ Every resource gets these limits automatically (per caller identity, per minute, within each Cloudflare location):
8
8
 
9
9
  | Operation | Default |
10
10
  |-----------|---------|
@@ -13,7 +13,7 @@ Every resource gets these limits automatically (per authenticated user, per minu
13
13
  | `update` | 200 / 60s |
14
14
  | `delete` | 200 / 60s |
15
15
 
16
- Numbers are loose enough that no legitimate user-driven traffic hits them, but tight enough to catch a runaway script before it burns the day's D1 budget. Override per-op or opt out wherever the defaults don't fit.
16
+ These defaults are request-shaping thresholds, not strict quotas. Override per operation or opt out wherever they do not fit.
17
17
 
18
18
  ## Override one operation
19
19
 
@@ -84,22 +84,24 @@ export default defineConfig({
84
84
 
85
85
  ```typescript
86
86
  rateLimit?: {
87
- read?: { limit: number, period: 10 | 60 };
88
- create?: { limit: number, period: 10 | 60 };
89
- update?: { limit: number, period: 10 | 60 };
90
- delete?: { limit: number, period: 10 | 60 };
87
+ read?: { limit: number, period: 10 | 60, delta?: number, bucket?: string };
88
+ create?: { limit: number, period: 10 | 60, delta?: number, bucket?: string };
89
+ update?: { limit: number, period: 10 | 60, delta?: number, bucket?: string };
90
+ delete?: { limit: number, period: 10 | 60, delta?: number, bucket?: string };
91
91
  } | false
92
92
  ```
93
93
 
94
94
  - `period` must be `10` or `60` (Cloudflare binding constraint — anything else is a compile-time error).
95
95
  - `limit` is a positive integer.
96
- - Omit an op to inherit the project default (or shipped default).
96
+ - `delta` is an optional **positive safe integer** (`1` through `Number.MAX_SAFE_INTEGER`). Omitted means one. It is static configuration, never derived from request bodies, row counts, or callbacks.
97
+ - `bucket` is an optional lowercase slug of 1–64 characters matching `[a-z0-9][a-z0-9_-]*`.
98
+ - Omit an operation to inherit the whole project policy (or shipped default). An explicit operation policy **replaces** the inherited policy: omitted `delta` becomes one and omitted `bucket` restores the route-specific key. Individual policy fields are not merged.
97
99
  - Set `false` at resource or project level to opt out.
98
100
 
99
101
  ## Resolution order
100
102
 
101
103
  1. Project `rateLimit: false` → no enforcement anywhere
102
- 2. Resource `rateLimit: false` → no enforcement on this resource
104
+ 2. Resource `rateLimit: false` → no CRUD enforcement or inherited action policy (an explicit record-action override still applies)
103
105
  3. Resource per-op override
104
106
  4. Project per-op default
105
107
  5. Quickback shipped defaults (1000 / 200 above)
@@ -108,7 +110,7 @@ Default-using resources collapse onto two shared bindings (`RL_1000_60`, `RL_200
108
110
 
109
111
  ## How requests are keyed
110
112
 
111
- Each handler composes a key as `<resource>:<op>:<identity>`. The identity is the caller's `userId`. A sessionless scope-only principal (for example an event pass, which has no `userId`) is keyed on its verified JWT subject, `scope:<kind>:<subjectId>`, so every pass holder gets their own bucket even when many of them share one network. Only callers with neither — routes that opt into PUBLIC access — fall back to the client's `cf-connecting-ip` header, then to the literal `'anon'` if that header is absent too.
113
+ Without an explicit bucket, each CRUD handler composes a key as `<resource>:<op>:<identity>`. The identity is the caller's `userId`. A sessionless scope-only principal (for example an event pass, which has no `userId`) is keyed on its verified JWT subject, `scope:<kind>:<subjectId>`, so every pass holder gets their own bucket even when many of them share one network. Callers with neither, including unauthenticated requests later rejected by a private handler, fall back to the client's `cf-connecting-ip` header, then to the literal `'anon'` if that header is absent too.
112
114
 
113
115
  This means:
114
116
 
@@ -118,23 +120,34 @@ This means:
118
120
 
119
121
  ## How limits compile
120
122
 
121
- The compiler walks every resource, collects unique `(limit, period)` tuples, and emits one Cloudflare binding per tuple to `wrangler.toml`:
123
+ The compiler walks every resource, collects unique `(limit, period)` tuples, and emits one Cloudflare binding per tuple to `wrangler.toml` (shown for a project named `my-app`):
122
124
 
123
125
  ```toml
124
- [[ratelimits]]
125
- name = "RL_1000_60"
126
- namespace_id = "60002000"
127
- simple = { limit = 1000, period = 60 }
128
-
129
126
  [[ratelimits]]
130
127
  name = "RL_200_60"
131
- namespace_id = "60001200"
128
+ namespace_id = "955231714"
132
129
  simple = { limit = 200, period = 60 }
130
+
131
+ [[ratelimits]]
132
+ name = "RL_1000_60"
133
+ namespace_id = "596007560"
134
+ simple = { limit = 1000, period = 60 }
133
135
  ```
134
136
 
135
- `namespace_id` is a stable per-tuple integer (`1000 + period * 1_000_000 + limit`), so it survives resource reordering and never drifts across recompiles.
137
+ Cloudflare scopes a `namespace_id` to the **account**, not the Worker: two Workers whose bindings share an id share counters for the same key. So the compiler derives each id from the Worker name (`name` in `quickback.config.ts`) and the `(limit, period)` tuple: a SHA-256 hash mapped into `10000000`–`999999999`. The id survives resource reordering and recompiles, and two projects on one account get different ids even when their limits match. If two tuples in one project hash to the same id, the later one (sorted by period, then limit) re-hashes until it is free. Renaming the Worker changes every id.
136
138
 
137
- Each generated CRUD handler invokes `c.env.RL_<L>_<P>.limit({ key })` between the auth gate and the access check. Hitting the limit returns:
139
+ > **Counters reset once on upgrade**
140
+ >
141
+ > Projects compiled before this scheme used `1000 + period * 1_000_000 + limit`, which gave every project the same ids, so anonymous IP-keyed limits in one project spent another project's budget whenever the resource and op names matched. The next deploy after recompiling moves each binding to its new id. Counters start from zero once, which only means a client can briefly get one extra window's worth of requests.
142
+
143
+
144
+ Named environments do not use these ids. Each target states its own in `environments.<name>.worker.bindings.rateLimits` (see [D1](/platform/database/d1) and [Neon](/platform/database/neon)). Pick ids that no other Worker on the account uses, and give staging and production different ones.
145
+
146
+ The platform auth middleware verifies credentials and populates `ctx` before resource routes run. CRUD rate-limit middleware runs before the handler's authentication requirement and access checks; action checks run near handler entry, also before those gates. Earlier platform or namespace middleware can reject a request before it reaches a limiter. This feature does not move any auth middleware.
147
+
148
+ The generated check makes one native `.limit({ key, delta })` call; a policy with no weight uses the native default of one. A successful check is not refunded if later authorization, validation, or execution fails. Missing bindings skip the check, including a Cloudflare environment where the binding is absent.
149
+
150
+ A rejected check returns:
138
151
 
139
152
  ```http
140
153
  HTTP/1.1 429 Too Many Requests
@@ -144,16 +157,18 @@ Content-Type: application/json
144
157
  { "error": "Rate limit exceeded", "code": "RATE_LIMITED", "retryAfter": 60 }
145
158
  ```
146
159
 
160
+ `Retry-After` and `retryAfter` are conservative period hints, not an exact reset time. The 429 response shape is unchanged.
161
+
147
162
  ## Batch endpoints
148
163
 
149
- Batch routes (`POST /batch`, `PATCH /batch`, `DELETE /batch`, `PUT /batch`) count as **a single request** against their op's limit, not N. A batch of 100 records consumes one token, not one hundred. This matches how most rate-limit configurations are actually written (caps on request volume, not row volume).
164
+ Batch routes (`POST /batch`, `PATCH /batch`, `DELETE /batch`, `PUT /batch`) charge their operation's static `delta` **once per request**, regardless of row count. With no weight configured, a batch of 100 records consumes one unit.
150
165
 
151
166
  ## Actions
152
167
 
153
168
  Custom actions (record-based and standalone) inherit rate limits without configuration:
154
169
 
155
- - **Record-based actions** (e.g. `POST /api/v1/claims/:id/approve`) inherit the resource's `update` (write) bucket. A user who hits the write limit on `claims` is also blocked from `approve`.
156
- - **Standalone actions** (e.g. `POST /api/v1/twilioIncoming`) inherit the project-default `update` bucket — they don't belong to a resource.
170
+ - **Record-based actions** (e.g. `POST /api/v1/claims/:id/approve`) inherit the resource's `update` policy (limit, period, weight, and optional shared bucket). Without an explicit bucket they still use their own action counter; exhausting CRUD `update` does not exhaust `approve`.
171
+ - **Standalone actions** (e.g. `POST /api/v1/twilioIncoming`) inherit the project-default `update` policy — they don't belong to a resource.
157
172
 
158
173
  Override either with the action's `rateLimit` field:
159
174
 
@@ -189,7 +204,7 @@ export default defineAction({
189
204
 
190
205
  Set `rateLimit: false` to opt the action out of enforcement entirely.
191
206
 
192
- **Key composition** — actions get their own keyspace so a generic resource bucket and an action's bucket never share counters:
207
+ **Key composition without `bucket`** — actions get their own keyspace:
193
208
 
194
209
  | Action kind | Key shape |
195
210
  |-------------|-----------|
@@ -198,7 +213,37 @@ Set `rateLimit: false` to opt the action out of enforcement entirely.
198
213
 
199
214
  The `:action:` infix is what keeps `update` (resource bucket) and `approve` (action bucket) from sharing counters when they happen to land on the same binding name.
200
215
 
201
- A record action's bulk variant (`POST /<resource>/batch/<action>`) shares its single-record sibling's key exactly, so a batch of N records consumes **one** token from the action's bucket per request — not N.
216
+ A record action's bulk variant (`POST /<resource>/batch/<action>`) shares its single-record sibling's key exactly and charges the configured static `delta` once. Action routes are exempted from the surrounding CRUD limiter, including actions with `rateLimit: false`, so there is no second CRUD charge.
217
+
218
+ ## Weighted requests and shared buckets
219
+
220
+ These policies combine inexpensive reads and an expensive export for the same caller:
221
+
222
+ ```typescript
223
+ // In defineTable(...):
224
+ rateLimit: {
225
+ read: { limit: 100, period: 60, delta: 1, bucket: 'catalog' },
226
+ }
227
+ ```
228
+
229
+ ```typescript
230
+ // In defineAction(...):
231
+ rateLimit: { limit: 100, period: 60, delta: 10, bucket: 'catalog' }
232
+ ```
233
+
234
+ The shared key is `qb:bucket:<project-name>:<bucket>:<identity>`. Project name and bucket come from validated configuration; identity uses the same verified user ID, verified scope subject, then IP/`anon` fallback described above. Request-supplied bucket names, weights, user IDs, or tenant IDs cannot select this key. A bucket combines selected request classes **per identity**, not all users or an entire organization.
235
+
236
+ Every declaration of a bucket in a compiled Worker, including project defaults, must agree on `(limit, period)`. Weights may differ. Conflicts fail compilation with both config paths. Different weights do not create additional bindings.
237
+
238
+ Cloudflare decides from the count **before** a call. A call below the threshold succeeds even when its weight takes the count over the threshold. A rejected call does not increment the count. Counts are approximate and eventually consistent within a location; other Cloudflare locations keep separate counts. Awaiting every call does not make the allowance exact. See [Cloudflare's weighted request contract](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/#weighted-requests).
239
+
240
+ Use `db.ledger` for strict balances, reservations, and finalization; weighted throttling is not billing, a strict business quota, or accounting. There are no refunds, reservations, dynamic weights, or post-execution adjustments in this API.
241
+
242
+ ### Projects, environments, and existing counters
243
+
244
+ Named environments retain their explicitly configured rate-limit namespace IDs. Use distinct namespaces per environment; the shared key intentionally includes the project name, not the environment name. Different project names separate explicit bucket keys, but deliberately reusing an account-level namespace **and the same key** can share counters across Workers. Legacy route keys remain unchanged and do not gain a project prefix.
245
+
246
+ Adding `bucket` selects a different counter; removing it returns to the route-specific counter. Changing a weight changes future consumption without migrating data. This feature does not reset account counters. Recompile and update generated project dependencies before local use. Weighted local development requires Wrangler **4.157.0+** and workers-types **5.20261106.1+**; Quickback's generated lower bounds are **4.157.0** and **5.20261118.1**, respectively. Wrangler requires **Node 22+**. No compatibility-date change is implied.
202
247
 
203
248
  ## Cardinality — how many bindings ship
204
249
 
@@ -207,22 +252,22 @@ Cloudflare bindings are sized at compile time (limit + period are baked in), so
207
252
  | Configuration | Bindings emitted |
208
253
  |---------------|------------------|
209
254
  | All defaults | 2 (`RL_1000_60` for reads, `RL_200_60` for writes) |
210
- | One project-wide read override (`read: { limit: 500, period: 60 }`) | 3 (`RL_500_60`, `RL_1000_60` ← only if some resource opts back into the default, `RL_200_60`) |
255
+ | One project-wide read override (`read: { limit: 500, period: 60 }`) | 2 (`RL_500_60`, `RL_200_60`); a third only if a resource explicitly declares another tuple |
211
256
  | Five resources tightening `delete` to `{ limit: 5, period: 60 }` | 3 (defaults + `RL_5_60` shared) |
212
257
  | Ten distinct per-action overrides at unique tuples | 12 (defaults + ten action buckets) |
213
258
 
214
259
  **Practical caps.** Cloudflare workers have generous binding limits (hundreds), so this is unlikely to be a real ceiling — but it's the reason every distinct `(limit, period)` you write on a `rateLimit` config widens the binding set, even when the same resource declares the same tuple multiple times. Resource-level configs that share a tuple share a binding and simply produce different runtime keys.
215
260
 
216
- **Key cardinality is separate.** Each binding holds an independent counter per key. A binding called via `claims:read:user_123` and `applications:read:user_123` consumes two separate counters in the same binding — fan-out cost lives in Cloudflare's distributed counter store, not in your binding count. The user-perceivable limit is "per (resource, op, user)", regardless of how many resources share the binding.
261
+ **Key cardinality is separate.** Each binding holds an independent counter per key. A binding called via `claims:read:user_123` and `applications:read:user_123` consumes two separate counters in the same binding — fan-out cost lives in Cloudflare's distributed counter store, not in your binding count. Without `bucket`, the allowance is per `(resource, op, identity)`. With `bucket`, selected operations use the shared key for that identity.
217
262
 
218
263
  ## Runtime support
219
264
 
220
265
  | Runtime | Rate limiting |
221
266
  |---------|---------------|
222
267
  | `cloudflare` | Backed by Cloudflare's native [Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) |
223
- | non-Cloudflare (`bun`, `node`) | Degrades safely — the check no-ops when the binding is absent from `c.env` |
268
+ | non-Cloudflare (`bun`, `node`) | No enforcement — the check no-ops when the binding is absent from `c.env` |
224
269
 
225
- Every generated rate-limit call site — CRUD middleware and custom actions alike — first looks up `c.env.RL_<limit>_<period>` and only calls `.limit({ key })` when the binding is present. On the Cloudflare runtime it always is. On other runtimes it isn't, so the check no-ops and the request proceeds — generated code never hard-depends on the binding.
270
+ Every generated rate-limit call site — CRUD middleware and custom actions alike — first looks up `c.env.RL_<limit>_<period>` and only calls the native limiter when the binding is present. Cloudflare configuration normally provisions it. If a binding is absent, the request proceeds without enforcement; this fail-open fallback also applies to non-Cloudflare runtimes. Do not use it as a strict quota guarantee.
226
271
 
227
272
  **Roadmap — Bun in-process shim.** An in-memory fixed-window shim (`src/lib/rate-limit-memory.ts`) that backs the same `c.env.RL_*.limit({ key })` call site with a process-memory token bucket is planned but **not yet emitted**. Until it lands, non-Cloudflare deployments that need enforcement should sit behind a Cloudflare WAF rule or an upstream rate limiter. A multi-instance Bun shim would additionally need sticky sessions (same user → same instance → same bucket), since a process-memory counter can't coordinate across processes.
228
273
 
@@ -232,7 +277,10 @@ The compiler errors on:
232
277
 
233
278
  1. `period` other than `10` or `60`
234
279
  2. Non-integer or non-positive `limit`
235
- 3. Unknown ops (e.g. `list` instead of `read`)
280
+ 3. Unknown operations or policy fields (e.g. `list` instead of `read`)
281
+ 4. A `delta` that is not a positive safe integer
282
+ 5. A malformed or overlong `bucket`
283
+ 6. Conflicting `(limit, period)` declarations for the same shared bucket
236
284
 
237
285
  ## Disabling vs. tightening — when to use which
238
286
 
@@ -91,11 +91,19 @@ interface ReadConfig {
91
91
  // `firewall` block is used (the common case).
92
92
  firewall?: FirewallConfig;
93
93
 
94
- // Serve reads through Cloudflare Hyperdrive's query cache (Postgres over
95
- // Hyperdrive only). Public, tenant-free data: requires
96
- // `firewall: { exception: true }`, a roles-only access admitting PUBLIC,
97
- // and the HYPERDRIVE_CACHED binding. See Neon → Cached public reads.
98
- cache?: "hyperdrive";
94
+ // Read caching — two independent engines:
95
+ // - "hyperdrive": Cloudflare Hyperdrive's query cache (Postgres over
96
+ // Hyperdrive only). Public, tenant-free data: requires
97
+ // `firewall: { exception: true }`, a roles-only access admitting PUBLIC,
98
+ // and the HYPERDRIVE_CACHED binding. See Neon → Cached public reads.
99
+ // - { engine: "workers", scope: "user", ttlSeconds }: user-scoped Workers
100
+ // Cache for authenticated D1 reads. See "Workers Cache" below.
101
+ cache?: "hyperdrive" | {
102
+ engine: "workers";
103
+ scope: "user"; // required; the only scope
104
+ ttlSeconds: number; // 1–300
105
+ consistency?: "committed";
106
+ };
99
107
 
100
108
  // Pagination for the collection GET and every view (one setting per
101
109
  // resource). `?limit=` above maxPageSize is clamped to it; OpenAPI
@@ -111,6 +119,16 @@ interface ReadConfig {
111
119
  // Mount the generated read routes (GET /, GET /:id, GET /views/*).
112
120
  // Default true. See "Tables only your actions read" below.
113
121
  routes?: boolean;
122
+
123
+ // Full-text `?search=` with SQLite FTS5 (cloudflare-d1, including tenant
124
+ // SQLite objects). See "Full-text search" below.
125
+ search?: {
126
+ engine: "fts5";
127
+ fields: { [column: string]: { weight?: number } }; // weight: integer 1–100, default 1
128
+ tokenizer?: "unicode61";
129
+ match?: "all";
130
+ ranking?: "field-match";
131
+ };
114
132
  }
115
133
 
116
134
  interface ViewConfig {
@@ -121,6 +139,194 @@ interface ViewConfig {
121
139
  }
122
140
  ```
123
141
 
142
+ ## Workers Cache
143
+
144
+ `read.cache: { engine: "workers", scope: "user", ttlSeconds }` caches a
145
+ resource's `GET /`, `GET /:id` and `GET /views/:name` responses **per
146
+ caller** in [Workers Cache](https://developers.cloudflare.com/workers/cache/).
147
+ It is for authenticated reads on Cloudflare D1. There is no public,
148
+ tenant-wide or shared mode.
149
+
150
+ {/* doc-compile: skip — config + resource fragments; the full defineConfig wrapper is shown in /configure. */}
151
+ ```typescript
152
+ // quickback.config.ts
153
+ database: defineDatabase("cloudflare-d1", {
154
+ readCache: { enabled: true },
155
+ }),
156
+
157
+ // features/docs/docs.ts
158
+ read: {
159
+ access: { roles: ["owner", "admin", "member"] },
160
+ cache: { engine: "workers", scope: "user", ttlSeconds: 60 },
161
+ },
162
+ ```
163
+
164
+ ### How a request is served
165
+
166
+ The Worker gets two entrypoints. The default entrypoint is the
167
+ **gateway**, and Workers Cache is off for it. `QuickbackReadCache` is a
168
+ private **inner** entrypoint with Workers Cache on. No route reaches it.
169
+
170
+ 1. The gateway runs the normal middleware on **every** request, hits
171
+ included. The session is re-read from Better Auth, the member row is
172
+ re-read from `AUTH_DB`, and the feature rate limiter counts the request.
173
+ 2. The gateway reads the features database's **data epoch**: one row
174
+ holding a random token, read on the primary. Every write the Worker
175
+ commits to the features database replaces the token with a new one (see
176
+ [The data epoch](#the-data-epoch)).
177
+ 3. The gateway signs an HMAC over the caller's authority snapshot, the
178
+ data epoch, the route, a policy fingerprint, the host
179
+ and the path + query. It then fetches the inner entrypoint with these
180
+ values as `ctx.props`. Workers Cache keys entries on path + query,
181
+ entrypoint, `ctx.props` and Worker version, so an entry is only reachable
182
+ with the same signed values. Cookies, `Authorization`, conditional and
183
+ `Range` headers are never forwarded.
184
+ 4. On a **miss**, the inner entrypoint verifies the signature and restores
185
+ the snapshot into `ctx`. It runs the **same** route handler on the
186
+ primary, so firewall, access and masking all run again. It then re-reads
187
+ the epoch. The response is stored only if nothing committed in between.
188
+ 5. The gateway renders the body through the normal ETag path. `ETag`, `304`
189
+ and `Cache-Control: private, no-cache` are byte-for-byte what an uncached
190
+ read returns. The platform cache never sees a `Set-Cookie`, request ID or
191
+ D1 bookmark.
192
+
193
+ Masking runs before caching. The cached body is the masked representation,
194
+ and the key contains every role, org and identity input masking reads. The
195
+ alternative was caching pre-mask rows and re-masking on every hit. That
196
+ would store unmasked data in a shared platform cache and depend on the hit
197
+ path re-masking correctly, so it was rejected.
198
+
199
+ ### What is in the key
200
+
201
+ | Dimension | Source |
202
+ |---|---|
203
+ | User, session | `ctx.userId`, `ctx.sessionId`. Two sessions of one user never share an entry. |
204
+ | Organization, roles | `ctx.activeOrgId`, `roles`, `orgRole`, `userRole`, `tierRoles`, `activeTeamId` |
205
+ | Data version | The data epoch token (`_quickback_data_epoch`) |
206
+ | Policy | Compile-time fingerprint of the resource's firewall, read access, views and masking, plus the Worker version |
207
+ | Request | Host, path and query string, in the order sent |
208
+ | Environment | Each named environment and Preview is its own Worker version. The optional `QB_READ_CACHE_NAMESPACE` var is in the key too. |
209
+
210
+ ### What is never cached
211
+
212
+ These take the ordinary uncached path:
213
+
214
+ - every lane except a Better Auth **session**: JWT bearer (its claims are not re-read per request), API keys, scope tokens, delegated principals, Cloudflare Access, share links and anonymous requests;
215
+ - requests carrying the read-replication bookmark header, `Cache-Control: no-cache` / `no-store`, or `Range`;
216
+ - any non-`200` answer. The gateway then re-runs the ordinary handler, so error bodies and status codes are unchanged;
217
+ - bodies over 1 MiB;
218
+ - requests where the D1 primary is unreachable, and every read before the first write mints an epoch token. Missing cache metadata falls back to an uncached authorized read. It never produces a stale hit.
219
+
220
+ The compiler refuses `engine: "workers"` on:
221
+
222
+ - any provider except `cloudflare-d1`;
223
+ - auth other than Better Auth;
224
+ - function-form access, and `relationship` / `permission` / `principal` arms;
225
+ - FK display columns and `include` (not supported yet);
226
+ - encrypted or derived-key columns;
227
+ - tenant Durable Object features (not supported yet).
228
+
229
+ `readCache: { enabled: true }` itself is refused next to any class the runtime
230
+ builds with the raw `env`: user Durable Objects (`bindings.durableObjects`),
231
+ service entrypoints (`bindings.serviceEntrypoints`) and the tenant Durable
232
+ Object. A D1 write there would commit without moving the data epoch.
233
+
234
+ ### The data epoch
235
+
236
+ `_quickback_data_epoch` is a compiler-owned table in the features database
237
+ with one row: a random 128-bit token stored as hex text. The generated D1 write wrapper (the one
238
+ [D1 recovery](/platform/database/recovery) uses for admission) is installed
239
+ on the features binding whenever `readCache` is on. Every write it sends goes
240
+ out as a native D1 batch, and the wrapper appends one statement to that batch:
241
+
242
+ ```sql
243
+ INSERT INTO _quickback_data_epoch (id, epoch) VALUES (1, lower(hex(randomblob(16))))
244
+ ON CONFLICT(id) DO UPDATE SET epoch = excluded.epoch
245
+ ```
246
+
247
+ The bump commits or rolls back with the write. Each token is minted once, so
248
+ it names exactly one state of the database: the state its write produced. A reader therefore never sees
249
+ new data under an old epoch. The gateway reads the epoch before it builds the
250
+ key, and the inner entrypoint reads it again after a fill. A write that
251
+ commits in between changes the second read, so the response is served but not
252
+ stored.
253
+
254
+ Covered, because they all reach the database through the wrapper:
255
+
256
+ - generated CRUD, batch and view routes, and actions, including `unsafe` ones;
257
+ - raw SQL through `prepare()` or `batch()`, including on a `withSession()` session;
258
+ - queue, cron and inbound-email handlers, durable-effect dispatch and data migrations;
259
+ - statements prepared on another handle and passed to `batch()`. They cannot be classified, so they count as writes.
260
+
261
+ Anything that is not provably read-only counts as a write, so the cache may
262
+ miss more than it has to, but never less. `exec()` is unavailable on the
263
+ wrapped binding because it cannot carry the bump.
264
+
265
+ Not covered: writers outside this Worker. That means `wrangler d1 execute`,
266
+ the dashboard console, another Worker bound to the same database, and schema
267
+ migrations. Their writes stay invisible to cached reads until the TTL
268
+ expires, unless the same command also mints a new token:
269
+
270
+ ```sql
271
+ UPDATE _quickback_data_epoch SET epoch = lower(hex(randomblob(16))) WHERE id = 1;
272
+ ```
273
+
274
+ Changing `QB_READ_CACHE_NAMESPACE` does the same for every entry. A deploy
275
+ changes the Worker version, which also starts a fresh cache. Never write a
276
+ token you made up or copied from elsewhere: only a freshly minted token is
277
+ guaranteed never to have addressed other data.
278
+
279
+ **Cost.** Each write batch on the features database carries one extra
280
+ single-row upsert. That is one more row written per batch, not per row, and
281
+ no extra round trip. D1 runs one writer per database, so writes are already
282
+ serialized. The shared row adds no lock beyond that, but every write does
283
+ update it. Reads cost one primary `SELECT` of the row per request, plus
284
+ one more after a fill. Writes without the table fail: apply the migration
285
+ that creates `_quickback_data_epoch` before deploying the Worker that bumps
286
+ it.
287
+
288
+ **Restores.** A D1 Time Travel restore rewinds the token with the data, back
289
+ to the token the restored state was written under. Entries under that token
290
+ were filled from exactly that state, so a hit after the restore is correct.
291
+ Every write after the restore mints a token that has never existed, so an
292
+ entry filled before the restore from a now-discarded later state can never be
293
+ hit. This holds however you restore, with or without
294
+ [recovery](/platform/database/recovery); the read path never consults the
295
+ control object.
296
+
297
+ **Upgrading from the counter epoch.** Earlier versions kept an integer
298
+ counter, which a restore could rewind and later writes then reuse. The
299
+ compiler now emits the column as `TEXT`, so the next migration rebuilds the
300
+ table and carries the old number over as text. A value that is not a minted
301
+ token is never used as a key: reads stay uncached until the first write after
302
+ the migration mints one.
303
+
304
+ ### Operations
305
+
306
+ | Control | Effect |
307
+ |---|---|
308
+ | `QB_READ_CACHE = "off"` (var) | Kill switch: no lookups, every read uncached. |
309
+ | `QB_READ_CACHE_NAMESPACE` (var) | Change it to orphan every existing entry before re-enabling. |
310
+
311
+ A hit still costs the gateway's authentication and one primary read of the
312
+ epoch row. It skips the resource query and render. A miss adds the inner
313
+ fetch and a second epoch read. Whether that saves anything depends on how
314
+ expensive the read is, so measure.
315
+
316
+ `readCache` still emits the operational-control Durable Object
317
+ (`QuickbackControl`, binding `QB_CONTROL`) even without recovery or durable
318
+ effects. Earlier versions read their restore generation from it, so
319
+ deployments already carry the class in their Durable Object migrations, and
320
+ removing it would need a `deleted_classes` migration. Nothing on the read path
321
+ calls it.
322
+
323
+ > Native Workers Cache does not run under local Vitest or Miniflare. The
324
+ > generated logic is tested against a controlled cache adapter. Check hits
325
+ > (`Cf-Cache-Status: HIT`) on a Preview or a deployed test Worker before you
326
+ > rely on them. If the platform never caches, every read still returns the
327
+ > correct authorized answer, just uncached.
328
+
329
+
124
330
  ## Tables only your actions read (`routes: false`)
125
331
 
126
332
  `read: { routes: false }` keeps `read.access` declared but mounts **no**
@@ -303,6 +509,9 @@ export default defineTable(notes, {
303
509
  });
304
510
  ```
305
511
 
512
+ An owned child can also be a soft-delete cascade target. The generated reader and
513
+ cascade share their schema import; no duplicate table definition or alias is needed.
514
+
306
515
  Both kinds land in the top-level `included` map keyed by the include token,
307
516
  then row PK, and both inherit the **target's full security surface** — its
308
517
  `read.access` (pre-record-evaluable only, compile-enforced), its firewall
@@ -393,6 +602,124 @@ GET /jobs?status.in=open,draft # IN clause
393
602
  | Pattern match | `?field.like=value` | `WHERE field LIKE '%value%'` |
394
603
  | In list | `?field.in=a,b,c` | `WHERE field IN ('a','b','c')` |
395
604
 
605
+ ### JSON projection queries
606
+
607
+ [Declare a JSON projection](/define/schema#indexed-json-projections-sqlite) to filter or sort a stored scalar without exposing a new row field:
608
+
609
+ ```text
610
+ GET /companies?industry=software
611
+ GET /companies?industry.in=software,finance&score.gte=80
612
+ GET /companies?sort=-score,id&limit=25&offset=25
613
+ ```
614
+
615
+ Only declared operators are accepted: `eq` supports equality and `.ne`; `in` adds comma-separated `.in`; `range` adds numeric inequalities. Strings remain strings. Numeric values must be complete, finite JSON numbers (no empty values, trailing text, hexadecimal or `Infinity`); booleans must be exactly `true` or `false`. Invalid operators, values or view capabilities return 400. Missing/null/wrong-type stored values are SQL NULL and do not match comparisons. There is no null operator or escaping of commas inside `.in` values; use equality for strings containing commas.
616
+
617
+ Views may list aliases in `query.filterable` or `query.sortable`, but cannot grant a capability the projection did not declare. A sortable alias may appear in `query.defaultSort`. Any sort containing an alias, including a default or mixed sort, uses **offset pagination**: `cursor`, `starting_after` and `ending_before` return 400, and both response cursors are null, even on an empty result. Duplicate and NULL sort values use the existing physical `id` tie-breaker. Filtering by an alias while sorting only physical columns retains ordinary cursor pagination.
618
+
619
+ Aliases are query-only. They cannot appear in `fields`, view output fields, create/update bodies, `searchable`, aggregates, group-by or rollup definitions. Responses still return the JSON source column under its normal field policy. Aggregate-only views can filter by an alias before computing aggregates of physical columns. Firewall, record access and soft-delete conditions constrain the rows, totals and aggregates together; a projection never grants access to another row or tenant.
620
+
621
+ OpenAPI and MCP advertise the permitted alias parameters per view. MCP forwards these arguments through the same authenticated HTTP routes. The schema registry carries separate `queryProjections` metadata; aliases are not editable CMS columns and do not imply a new CMS control.
622
+
623
+ ## Full-text search (`read.search`)
624
+
625
+ Without a declaration, `?search=` is an escaped substring `LIKE` over the
626
+ view's searchable columns. Declare `read.search` to switch the resource to
627
+ **SQLite FTS5 token matching** — a deliberate behavior change, never applied
628
+ silently to an existing resource:
629
+
630
+ ```typescript title="quickback/features/articles/articles.ts"
631
+ import { feature, q } from "@quickback/compiler";
632
+
633
+ export default feature("articles", {
634
+ columns: {
635
+ id: q.id(),
636
+ organizationId: q.scope("organization"),
637
+ title: q.text().required(),
638
+ body: q.text().optional(),
639
+ status: q.enum(["draft", "published"]).optional(),
640
+ ...q.audit(),
641
+ ...q.softDelete(),
642
+ },
643
+ guards: { createable: ["title", "body", "status"], updatable: ["title", "body", "status"] },
644
+ read: {
645
+ access: { roles: ["member"] },
646
+ search: {
647
+ engine: "fts5",
648
+ fields: { title: { weight: 3 }, body: { weight: 1 }, status: {} },
649
+ },
650
+ defaultView: "all",
651
+ views: {
652
+ all: { fields: ["id", "title", "body", "status"] },
653
+ // A view may NARROW the indexed fields; it can never widen them.
654
+ headlines: { fields: ["id", "title"], query: { searchable: ["title"] } },
655
+ },
656
+ },
657
+ create: { access: { roles: ["member"] } },
658
+ update: { access: { roles: ["member"] } },
659
+ delete: { access: { roles: ["member"] }, mode: "soft" },
660
+ });
661
+ ```
662
+
663
+ ```text
664
+ GET /articles?search=quarterly budget # every term must match
665
+ GET /articles/views/headlines?search=budget # title only
666
+ GET /articles?search=budget&sort=-createdAt # explicit physical sort, cursors allowed
667
+ ```
668
+
669
+ **Matching.** The input is split on whitespace into at most 16 literal terms
670
+ (256 bytes). Each term is quoted and bound as data: clients cannot send FTS
671
+ operators, column filters, prefixes or SQL. Every term must occur in at least
672
+ one of the view's eligible fields; terms may match different fields. The
673
+ `unicode61` tokenizer folds case and Latin diacritics (`cafe` matches
674
+ `Café`) and matches whole tokens, not substrings (`caf` does not match
675
+ `Café`); a term with punctuation inside (`budget-2026`) is a phrase of its
676
+ tokens. Queries are NFC-normalized. This is not a language analyzer — there is
677
+ no stemming or synonym support. Empty or whitespace-only input means no
678
+ search; input with no letter or digit is a 400.
679
+
680
+ **Ranking.** Without `?sort=`, results are ordered by **field-match
681
+ relevance**: the sum of the weights of the caller's eligible fields that
682
+ contain at least one term, then `id`. It looks only at the matching row
683
+ itself — no corpus statistics (not BM25) — so rows of other tenants, other
684
+ users or soft-deleted rows can never change your order. Relevance order uses
685
+ **offset pagination**: `cursor`, `starting_after` and `ending_before` return
686
+ 400 and both response cursors are `null`. An explicit `?sort=` keeps its
687
+ normal meaning, including keyset cursors. Responses carry no scores or
688
+ snippets.
689
+
690
+ **Authorization.** The match is a predicate on the base table combined with
691
+ the firewall, access (including record arms), soft-delete and filter
692
+ predicates **before** pagination, so rows, `?total=true` and a view's
693
+ aggregations all describe the same authorized set. Aggregate-only views ignore
694
+ `?search=`, as before.
695
+
696
+ **Fields.** Only plain `text`, `url` and `enum` columns of a q-DSL table with
697
+ an `id` primary key. Masked (declared or auto-detected), encrypted, sealed,
698
+ secret, vault/storage-reference, JSON and array columns are compile errors —
699
+ even when some role can reveal the value — because matching runs for every
700
+ caller. Adding such a policy to an indexed field later fails the next compile.
701
+ `snippet`, `highlight`, `rank`/score output and other tokenizers are rejected.
702
+ Other database providers fail compilation; use [custom SQL](/define/escape-hatches)
703
+ for provider-native search there.
704
+
705
+ **Index lifecycle.** The index is derived state: an FTS5 external-content
706
+ table plus `AFTER INSERT / UPDATE OF <fields> / DELETE` triggers, so every
707
+ write — generated CRUD, batch, actions and raw SQL — maintains it in the same
708
+ transaction. Each declaration change appends one
709
+ `NNNN_quickback_search_<hash>.sql` migration that drops the previous index
710
+ generation, recreates it, rebuilds it from the table and verifies it before
711
+ creating the triggers; unchanged declarations append nothing, and removing
712
+ `read.search` appends a migration that drops only the owned index objects.
713
+ Applied migrations are never edited. See
714
+ [D1 → Full-text search](/platform/database/d1#full-text-search-readsearch) for
715
+ rebuilds, recovery and limits. Until this build's index migration is applied,
716
+ searches return **503 `SEARCH_INDEX_UNAVAILABLE`** — never a silent `LIKE`
717
+ fallback.
718
+
719
+ OpenAPI advertises the engine, eligible fields, weights and the relevance
720
+ pagination contract per route (`x-search`); MCP list tools inherit the same
721
+ route contract.
722
+
396
723
  ## Sorting & Pagination
397
724
 
398
725
  ```
@@ -111,6 +111,16 @@ export default defineConfig({
111
111
 
112
112
  Resource definitions reference declared roles by name in `roles: [...]` arrays exactly like BA roles or pseudo-roles. The compiler rewrites the access tree at build time so the runtime route does an inline relationship lookup against the declared table.
113
113
 
114
+ > **The consuming row must carry the same resource column**
115
+ >
116
+ > `resource: { column: "issueId" }` compares the relationship's `issueId` to
117
+ > `record.issueId`, not `record.id`. It does not infer an FK-to-primary-key mapping.
118
+ > For issues keyed by `id` and assignment rows keyed by `issueId`, use the
119
+ > [scoped update action example](/define/issue-tracker-example) to preserve both
120
+ > reporter and assignee editing. Test the assignee branch over HTTP; a valid
121
+ > compile alone does not prove this join is mapped correctly.
122
+
123
+
114
124
  #### Supported relationship-role surfaces
115
125
 
116
126
  | Surface | Status | Notes |