@quickback-dev/cli 0.72.9 → 0.72.10

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 (210) 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 +63 -22
  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/read-replication.md +9 -0
  135. package/dist/skill/docs/platform/database/recovery.md +292 -0
  136. package/dist/skill/docs/platform/database/using-d1.md +152 -2
  137. package/dist/skill/docs/platform/index.md +1 -0
  138. package/dist/skill/docs/platform/operations/budgets.md +224 -0
  139. package/dist/skill/docs/platform/queues/handlers.md +1 -0
  140. package/dist/skill/docs/platform/queues/index.md +18 -0
  141. package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
  142. package/dist/skill/docs/platform/storage/using-r2.md +13 -0
  143. package/dist/skill/docs/platform/vector/embeddings.md +28 -4
  144. package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
  145. package/dist/skill/docs/platform/workflows/index.md +385 -0
  146. package/dist/skill/docs/start/deploy-browser.md +51 -0
  147. package/dist/skill/docs/start/deploy.md +97 -1
  148. package/dist/skill/docs/tooling/cli.md +117 -0
  149. package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
  150. package/dist/skill/docs/ui/account/customization.md +4 -0
  151. package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
  152. package/package.json +1 -1
  153. package/src/skill/SKILL.md +9 -3
  154. package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
  155. package/src/skill/docs/api/batch-operations.md +19 -0
  156. package/src/skill/docs/api/caching.md +17 -0
  157. package/src/skill/docs/api/crud.md +9 -0
  158. package/src/skill/docs/api/errors.md +31 -2
  159. package/src/skill/docs/api/query-params.md +6 -0
  160. package/src/skill/docs/changelog/index.md +1 -0
  161. package/src/skill/docs/configure/agents.md +1 -1
  162. package/src/skill/docs/configure/bindings.md +177 -1
  163. package/src/skill/docs/configure/cloudflare-access.md +43 -0
  164. package/src/skill/docs/configure/domains.md +1 -1
  165. package/src/skill/docs/configure/providers.md +5 -0
  166. package/src/skill/docs/configure/tenant-databases.md +627 -14
  167. package/src/skill/docs/define/access.md +26 -0
  168. package/src/skill/docs/define/actions/defining.md +7 -1
  169. package/src/skill/docs/define/actions/index.md +5 -0
  170. package/src/skill/docs/define/actions/scoped-db.md +127 -1
  171. package/src/skill/docs/define/authoring-basics.md +92 -0
  172. package/src/skill/docs/define/changesets.md +8 -0
  173. package/src/skill/docs/define/encryption.md +48 -2
  174. package/src/skill/docs/define/feature.md +17 -2
  175. package/src/skill/docs/define/guards.md +11 -3
  176. package/src/skill/docs/define/index.md +1 -1
  177. package/src/skill/docs/define/invariants.md +321 -0
  178. package/src/skill/docs/define/issue-tracker-example.md +225 -0
  179. package/src/skill/docs/define/masking.md +3 -3
  180. package/src/skill/docs/define/rate-limit.md +63 -22
  181. package/src/skill/docs/define/read.md +332 -5
  182. package/src/skill/docs/define/relationships.md +10 -0
  183. package/src/skill/docs/define/schema.md +137 -10
  184. package/src/skill/docs/define/scopes.md +1 -0
  185. package/src/skill/docs/define/transitions.md +9 -0
  186. package/src/skill/docs/define/triggers.md +127 -1
  187. package/src/skill/docs/platform/api-contract/index.md +35 -4
  188. package/src/skill/docs/platform/auth/api-keys.md +26 -3
  189. package/src/skill/docs/platform/auth/index.md +5 -2
  190. package/src/skill/docs/platform/auth/plugins/index.md +1 -1
  191. package/src/skill/docs/platform/database/d1.md +73 -1
  192. package/src/skill/docs/platform/database/durable-effects.md +224 -0
  193. package/src/skill/docs/platform/database/read-replication.md +9 -0
  194. package/src/skill/docs/platform/database/recovery.md +292 -0
  195. package/src/skill/docs/platform/database/using-d1.md +152 -2
  196. package/src/skill/docs/platform/index.md +1 -0
  197. package/src/skill/docs/platform/operations/budgets.md +224 -0
  198. package/src/skill/docs/platform/queues/handlers.md +1 -0
  199. package/src/skill/docs/platform/queues/index.md +18 -0
  200. package/src/skill/docs/platform/realtime/table-changes.md +1 -0
  201. package/src/skill/docs/platform/storage/using-r2.md +13 -0
  202. package/src/skill/docs/platform/vector/embeddings.md +28 -4
  203. package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
  204. package/src/skill/docs/platform/workflows/index.md +385 -0
  205. package/src/skill/docs/start/deploy-browser.md +51 -0
  206. package/src/skill/docs/start/deploy.md +97 -1
  207. package/src/skill/docs/tooling/cli.md +117 -0
  208. package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
  209. package/src/skill/docs/ui/account/customization.md +4 -0
  210. package/src/skill/docs/ui/admin/record-layouts.md +3 -3
@@ -57,16 +57,166 @@ audit databases — races each statement against the deadline:
57
57
  | Write (anything else, and any `batch` containing a write) | `500 DB_WRITE_OUTCOME_UNKNOWN` | Re-read the record, then decide. The statement was **not** cancelled on the backend and may still commit |
58
58
 
59
59
  Each timeout also logs one structured line —
60
- `{ level: "error", event: "DB_DEADLINE", binding, kind, ms, sql }` (SQL
61
- truncated to 200 chars). Workers Logs indexes the JSON fields, so in the
60
+ `{ level: "error", event: "DB_DEADLINE", version: 1, binding, kind, ms, statements, fingerprint }`. `fingerprint` is the statement's [structural fingerprint](#fingerprints) (`null` for a multi-statement batch); SQL text and parameters are never logged. Workers Logs indexes the JSON fields, so in the
62
61
  dashboard or `wrangler tail --format json` filter on `event = "DB_DEADLINE"`
63
62
  and group by `binding` / `kind` to track stalls over time. The response the
64
63
  client saw carries the same `binding` in `details`. Unset, nothing changes: no wrapper is emitted and queries are
65
64
  unbounded, as before. The option is D1-only; Postgres drivers carry their own
66
65
  statement timeouts. With [`readReplication`](/platform/database/read-replication) on, the deadline wraps the request's D1 session too.
67
66
 
67
+ ## Sampled query diagnostics
68
+
69
+ D1 can return rows read/written, SQL execution time, retry attempts and replica
70
+ metadata for a statement. Turn on sampled observations in the D1 provider:
71
+
72
+ ```ts
73
+ import { defineDatabase } from '@quickback/compiler';
74
+
75
+ const database = defineDatabase('cloudflare-d1', {
76
+ diagnostics: { sampleRate: 0.01, slowMs: 100, rowsReadWarning: 10000 },
77
+ });
78
+ ```
79
+
80
+ All three fields are required and unknown fields are a compile error.
81
+ `sampleRate` is between 0 and 1; `slowMs` and `rowsReadWarning` are finite and
82
+ nonnegative. They are your choices, not Cloudflare limits. `diagnostics` adds
83
+ no query deadline and changes no retry behavior. It also emits
84
+ `reports/d1-query-catalog.json`, which the [CLI commands](#explain-and-query-insights)
85
+ read. To get the catalog without runtime sampling, set `sampleRate: 0`.
86
+
87
+ ### `D1_QUERY` events
88
+
89
+ Each sampled statement logs one JSON line:
90
+
91
+ ```json
92
+ { "event": "D1_QUERY", "version": 1, "operation": "GET /api/v1/projects",
93
+ "binding": "DB", "method": "raw", "outcome": "success",
94
+ "fingerprint": "SELECT \"projects\" . \"id\" FROM \"projects\" WHERE ( \"projects\" . \"organization_id\" = ? AND \"projects\" . \"deleted_at\" IS NULL ) LIMIT ?",
95
+ "durationMs": 3.1, "metadataAvailable": false, "rowsRead": null, "rowsWritten": null,
96
+ "sqlDurationMs": null, "attempts": null, "region": null, "primary": null,
97
+ "batchIndex": null, "aggregate": false, "statementCount": null, "observedStatements": null,
98
+ "slow": false, "rowsReadWarning": null }
99
+ ```
100
+
101
+ - **`operation`** is the request method plus the route pattern Hono matched
102
+ (`/api/v1/projects/:id`, never the concrete URL). It matches the `route` of an
103
+ entry in the catalog. It is `null` outside a request (cron, queue and email
104
+ runners).
105
+ - **Missing cost is `null`, not zero.** Drizzle runs SELECTs through `.raw()`,
106
+ which returns no D1 metadata, and `.first()` returns none either. Quickback
107
+ does not swap those calls or run a second query to measure them, so
108
+ `metadataAvailable: false` is the normal case for reads. Writes (`run`) and
109
+ native batches carry metadata.
110
+ - **`durationMs`** is the time measured in the Worker, including waiting and
111
+ transport. `sqlDurationMs` is D1's own execution time when it reports one.
112
+ - **Outcomes:** `success`, `error`, `timeout` (a read past
113
+ [`queryTimeoutMs`](#backend-stalls)), `write_outcome_unknown`
114
+ (a write past the deadline that may still commit) and `replica_wait_timeout`.
115
+ A statement that finishes after its deadline logs nothing more and is never
116
+ retried.
117
+
118
+ Sampling is decided once per request. The request's database middleware gives
119
+ every handle in that request one sampling decision and a shared budget of 20
120
+ events. Handles created outside a request, such as service jobs, get their own
121
+ 20-event budget. A native batch logs one summary event (`aggregate: true`) that
122
+ holds the batch's duration. It also logs up to 19 per-statement events
123
+ (`batchIndex`) with cost but no duration. Never add the per-statement events to
124
+ the summary. `observedStatements` shows how many leading statements were
125
+ observed: a sampled prefix is not a full account. `exec`, `dump` and bindings
126
+ you call directly, outside the generated adapters, are not instrumented. A
127
+ failing log sink never changes a query's result.
128
+
129
+ ### Fingerprints
130
+
131
+ A fingerprint is the statement reduced to its structure. It keeps:
132
+
133
+ - SQL keywords and a fixed list of SQLite functions;
134
+ - punctuation and operators;
135
+ - **compiler-known identifiers only**, which are the table and column names of
136
+ your generated Drizzle schema, double-quoted.
137
+
138
+ Every string, number, blob, parameter and comment becomes `?` or is dropped. Any
139
+ other name becomes the word `identifier`. SQL the tokenizer cannot classify is
140
+ `unclassified`: an unterminated quote, a second statement, an unknown character
141
+ or more than 16 KiB. That includes SQL that is not `SELECT`/`WITH`/`INSERT`/`UPDATE`/`DELETE`.
142
+ Fingerprints describe structure, and two queries with the same shape share one,
143
+ so they are not unique query IDs. SQL text, bound values, rows and errors never
144
+ appear in an event.
145
+
146
+ Because Drizzle quotes every identifier and binds every value, a fingerprint
147
+ of a generated query is valid SQL with `?` placeholders. That is what makes it
148
+ explainable.
149
+
150
+ ### Explain and Query Insights
151
+
152
+ Both commands are read-only. They need `reports/d1-query-catalog.json` from a
153
+ build with `diagnostics` set.
154
+
155
+ ```bash
156
+ # Plan the exact shape a route issued, against your local D1 (the default)
157
+ quickback db explain --binding DB \
158
+ --fingerprint 'SELECT "projects" . "id" FROM "projects" WHERE ( "projects" . "organization_id" = ? AND "projects" . "deleted_at" IS NULL ) LIMIT ?' \
159
+ --input ./explain-params.json # ["org_synthetic", 20]
160
+ ```
161
+
162
+ `db explain` plans a fingerprint you copied from a `D1_QUERY` event or from
163
+ `db insights`. The fingerprint is the production query builder's own output,
164
+ with the firewall predicates already in it. No second query builder exists that
165
+ could leave them out. The command accepts only a canonical `SELECT`
166
+ fingerprint whose names are all in the catalog. Literals, unknown names,
167
+ writes, comments and second statements are refused. It fills each `?` with your
168
+ synthetic `--input` values, which must be primitives, encoded as SQLite literals
169
+ (never pasted into the SQL). Then it runs one `EXPLAIN QUERY PLAN` through
170
+ `wrangler d1 execute`. For a remote plan, pass `--remote --env <target>`. The
171
+ target account and database are printed before anything runs, and there is no
172
+ remote fallback.
173
+
174
+ The output lists the plan rows, the indexes used, any full `SCAN` and any
175
+ `USE TEMP B-TREE` sort, with advice. A plan is the planner's estimate, not
176
+ measured cost. Read it next to sampled `rowsRead` and Query Insights.
177
+ Quickback's [automatic indexes](/define/schema) cover these columns:
178
+
179
+ - the tenant column, together with `deleted_at`;
180
+ - foreign keys;
181
+ - filter-like columns;
182
+ - view `sortable` columns.
183
+
184
+ Anything else is a manual index in the table's index callback. Quickback never
185
+ creates or migrates an index from diagnostics: index changes are advice only.
186
+
187
+ ```bash
188
+ quickback db insights --env staging --binding DB --window 24h --sort reads --aggregate sum --limit 20 --json
189
+ ```
190
+
191
+ `db insights` reads remote D1 Query Insights through the project's installed
192
+ Wrangler 4.x (`wrangler d1 insights`). It needs the following:
193
+
194
+ - an explicit `--binding`, with a real database ID and an explicit account ID
195
+ in the generated target;
196
+ - a Wrangler that you installed and authenticated yourself;
197
+ - an API token with **Account Analytics Read**.
198
+
199
+ The target identity is printed before Wrangler is called. An unknown binding
200
+ never widens to account-wide analytics. To ask for account-wide analytics, you
201
+ must say so: `--account <id> --all-databases`, without `--binding`. Query
202
+ strings are redacted to fingerprints using the catalog's identifiers before
203
+ anything is printed, so they match runtime fingerprints and feed straight into
204
+ `db explain`.
205
+
206
+ Results are top-N adaptive analytics, not account totals. Averages are
207
+ recomputed from sums and counts, and a zero count gives `null`. Wrangler
208
+ reports a missing sum or average as `0`, so a zero is not proof of zero cost.
209
+ The Wrangler command is experimental, so the CLI checks the shape of its
210
+ output. An unknown format, a permission failure or a failed command produces an
211
+ error code, never zero metrics or raw output.
212
+
213
+ References: [D1 return objects](https://developers.cloudflare.com/d1/worker-api/return-object/),
214
+ [index inspection](https://developers.cloudflare.com/d1/best-practices/use-indexes/),
215
+ [Query Insights](https://developers.cloudflare.com/d1/observability/metrics-analytics/#query-insights).
216
+
68
217
  ## Related
69
218
 
70
219
  - [D1 Setup](/platform/database/d1) — Bindings and wrangler config
71
220
  - [Read replication](/platform/database/read-replication) — Serve reads from regional replicas with the Sessions API
72
221
  - [Schema](/define/schema) — Defining your database schema
222
+ - [CLI: D1 diagnostics](/tooling/cli#d1-diagnostics) — `quickback db explain` and `quickback db insights`
@@ -11,6 +11,7 @@
11
11
  | [Realtime](/platform/realtime) | Durable Objects | WebSocket for live updates |
12
12
  | [Queues](/platform/queues) | Cloudflare Queues | Background jobs, webhook delivery |
13
13
  | [Schedules](/platform/schedules) | Cron Triggers | `defineSchedule` cron jobs, server-internal |
14
+ | [Workflows](/platform/workflows) | Cloudflare Workflows | `defineWorkflow` durable multi-step runs, actor authority re-checked per step |
14
15
  | [Email](/platform/email) | Email Workers | `defineEmail` inbound handlers, server-internal |
15
16
  | [Vector & AI](/platform/vector) | Workers AI | Embeddings, semantic search |
16
17
  | [Webhooks](/platform/webhooks) | Hono + Queues | Signed inbound, retried outbound |
@@ -0,0 +1,224 @@
1
+ # Account spend policies
2
+
3
+ `quickback platform budget` manages Cloudflare **spend policies**: email alerts
4
+ and spending limits for Workers and Durable Objects. It wraps the official
5
+ [`cf billing spend-policies`](https://developers.cloudflare.com/billing/manage/spend-management/cli/)
6
+ commands in a preview, review and apply workflow. Each change is checked
7
+ against the policy's version and recorded in a local receipt.
8
+
9
+ > These are **account-level platform controls**. Each policy covers one product
10
+ > (all Workers, or all Durable Objects) across one Cloudflare account. A policy
11
+ > cannot target one Worker, one Durable Object namespace or one tenant, so it is
12
+ > not a per-tenant quota. It is also not an invoice cap. Usage reporting and
13
+ > blocking take time, and some charges continue during a pause, so the invoice
14
+ > can exceed the threshold.
15
+
16
+
17
+ ## What Cloudflare supports
18
+
19
+ | Control | Supported here | Notes |
20
+ |---------|----------------|-------|
21
+ | Workers or Durable Objects email alert (`notification`) | Yes | Emails at 80% and 100% of the threshold. The product keeps running. |
22
+ | Workers or Durable Objects spending limit (`usage_block`) | Yes | Blocks the product's supported operations across the account. One enabled limit per product. |
23
+ | Account-wide budget alert | **No** | Dashboard only (**Billing → Billable Usage**). Cloudflare has no CLI or API for it, so a `budgetAlerts` key in the document is a validation error. |
24
+ | Current recorded spend | **No** | `cf` has no command that reads current spend. Plans and status show it as `unknown`, and show the latest 80% and 100% threshold events instead. |
25
+
26
+ Spend policies do **not** cover the Workers Paid subscription fee, Workers KV,
27
+ R2, D1, Queues, Workers AI, Vectorize or Durable Objects stored data.
28
+
29
+ A Workers limit can stop HTTP requests, cron triggers, queue consumers and other
30
+ invocations for every Worker on the account. A Durable Objects limit pauses
31
+ requests and operations. Existing WebSockets and some work in progress can
32
+ continue. See Cloudflare's notes on
33
+ [Workers](https://developers.cloudflare.com/workers/platform/spend-management/)
34
+ and [Durable Objects](https://developers.cloudflare.com/durable-objects/platform/spend-management/).
35
+
36
+ ## Prerequisites
37
+
38
+ - The [`cf` CLI](https://developers.cloudflare.com/cf/get-started/), signed in
39
+ or with `CLOUDFLARE_API_TOKEN` set.
40
+ - **Account → Billing → Read** to run `status`, `plan` and `history`.
41
+ **Billing → Edit** to run `apply`. Cloudflare checks these permissions, not
42
+ Quickback.
43
+
44
+ ## The account is always explicit
45
+
46
+ Every command needs `--account <id>`, or `--env <target>` to use that target's
47
+ `accountId` from `quickback.config.ts`. Quickback never takes the account from
48
+ your current `cf` or Wrangler login. The first line of output names the
49
+ account. Each `cf` call runs with `CLOUDFLARE_ACCOUNT_ID` set to that account,
50
+ which overrides any ambient value (Quickback prints a warning when it does).
51
+ Your global `cf` profile is not modified.
52
+
53
+ With `--env`, the plan also lists the other deployment targets on the same
54
+ account, because a limit stops all of them.
55
+
56
+ ## The budget document
57
+
58
+ Policies are declared in a JSON file that operators own. It is kept apart from
59
+ `quickback.config.ts`, because one account can host several projects, and
60
+ `quickback build` and `quickback deploy` never apply account policies.
61
+
62
+ ```json title="budget.json"
63
+ {
64
+ "version": 1,
65
+ "owner": "platform-ops",
66
+ "accountId": "0123456789abcdef0123456789abcdef",
67
+ "policies": [
68
+ { "key": "workers-alert", "product": "workers", "action": "notification", "thresholdCents": 5000, "enabled": true, "email": "ops@example.com" }
69
+ ]
70
+ }
71
+ ```
72
+
73
+ This example sets an alert only. The amounts and addresses on this page are
74
+ illustrations, not recommendations. To add a limit, choose it deliberately:
75
+
76
+ ```json
77
+ { "key": "objects-limit", "product": "durable_objects", "action": "usage_block", "thresholdCents": 10000, "enabled": true, "email": "ops@example.com" }
78
+ ```
79
+
80
+ | Field | Rules |
81
+ |-------|-------|
82
+ | `owner` | Lowercase slug naming the team that owns these policies. It labels ownership. It does not grant permission. |
83
+ | `accountId` | 32 lowercase hex characters. Must equal `--account` or the `--env` target's account. |
84
+ | `key` | Unique lowercase slug. Quickback tracks ownership by `(account, owner, key)`, never by display name. |
85
+ | `product` | `workers` or `durable_objects`. No other product supports spend policies. |
86
+ | `action` | `notification` (alert) or `usage_block` (limit). |
87
+ | `thresholdCents` | Positive whole number of US cents (`5000` = $50). Zero, fractions and strings are rejected. |
88
+ | `enabled` | Required `true` or `false`. |
89
+ | `email` | One address. Required for alerts. A limit without one sends no email. |
90
+ | `name` | Optional display name (1–200 bytes). Defaults to `quickback <owner>/<key>`. |
91
+ | `adoptPolicyId` | Optional. Takes ownership of an existing policy, previewed in the plan like any other change. |
92
+
93
+ Unknown keys fail validation, and the CLI reports every problem at once. Never
94
+ put API tokens in this file.
95
+
96
+ ## Plan, review, apply
97
+
98
+ ```bash
99
+ quickback platform budget plan budget.json --out budget-plan.json --account 0123456789abcdef0123456789abcdef
100
+ quickback platform budget apply budget-plan.json --confirm <digest> --account 0123456789abcdef0123456789abcdef
101
+ ```
102
+
103
+ `plan` is read-only. It lists:
104
+
105
+ - every policy on the account, marked as owned or not owned;
106
+ - recorded spend as `unknown`;
107
+ - each operation, with before and after state, recipients, and its expected
108
+ policy version;
109
+ - consequences, such as "can block every Worker invocation as soon as
110
+ Cloudflare evaluates it", "lowers the threshold" or "lifts any block and
111
+ permits further spending";
112
+ - a SHA-256 digest of the whole plan file.
113
+
114
+ `plan` refuses to:
115
+
116
+ - create a second enabled limit for a product while a policy it does not own
117
+ is already one. Turn that policy off, or adopt it explicitly;
118
+ - change a policy's product;
119
+ - adopt a policy that is already owned.
120
+
121
+ When you remove an owned policy from the document, the plan turns it **off**
122
+ rather than deleting it.
123
+
124
+ `apply` checks the `--confirm` digest against the plan file, so a file edited
125
+ after review is refused. It then reads every policy again before changing
126
+ anything. A policy at a different version than the plan expected stops the
127
+ run: re-plan and review the new state. Quickback never merges changes made by
128
+ another operator. Each update resends the whole policy, as Cloudflare requires,
129
+ with `--if-match <version>`.
130
+
131
+ ## Ownership and receipts
132
+
133
+ Operator state lives in `--state` (default `.quickback/platform-budget/`).
134
+ Files are written with mode `0600`:
135
+
136
+ - `ownership.json` maps `(account, owner, key)` to the policy id, the last
137
+ version Quickback saw, and a configuration hash. When a policy was changed
138
+ outside Quickback, the next plan says so.
139
+ - `receipts.jsonl` is append-only. Quickback writes an `intent` line before
140
+ each change and a `done` line after it, with the before and after state and
141
+ the version Cloudflare returned. If the `intent` write fails, nothing is sent
142
+ to Cloudflare. If the `done` write fails after Cloudflare accepted a change,
143
+ `apply` stops and names the policy and version.
144
+
145
+ Keep this directory somewhere durable and private. If several operators apply
146
+ changes, share it, for example in a private repository. Receipts contain
147
+ notification email addresses.
148
+
149
+ ### Partial failure and resume
150
+
151
+ Each policy is changed separately, so partial success is possible. `apply`
152
+ lists the operations that completed, the one that failed, and those not yet
153
+ tried. To resume, run the same `apply` again. It skips operations that already
154
+ completed. If the failure was a version conflict (HTTP 412), re-plan instead.
155
+
156
+ If a create's response is lost, its outcome is unknown. On the next run,
157
+ `apply` looks for exactly one policy it does not own that matches the create.
158
+ If it finds one, it records it and does not create it again. If it finds more
159
+ than one, it stops. Check `history` before trying again.
160
+
161
+ ## Rollback
162
+
163
+ ```bash
164
+ quickback platform budget rollback-plan budget-plan.json --out rollback.json --account 0123456789abcdef0123456789abcdef
165
+ quickback platform budget apply rollback.json --confirm <digest> --account 0123456789abcdef0123456789abcdef
166
+ ```
167
+
168
+ Rollback does not clean up automatically. It builds a new plan for you to
169
+ review:
170
+
171
+ - a changed policy goes back to the full state recorded before it was changed;
172
+ - a created policy is turned off.
173
+
174
+ `rollback-plan` refuses if a policy changed after the original apply, rather
175
+ than overwriting that edit. It also refuses if the policy's ownership no longer
176
+ matches the receipt. Raising or turning off a limit permits further spending,
177
+ and the plan says so.
178
+
179
+ ## Status and history
180
+
181
+ ```bash
182
+ quickback platform budget status --account 0123456789abcdef0123456789abcdef --json
183
+ quickback platform budget history --account 0123456789abcdef0123456789abcdef
184
+ quickback platform budget history --account 0123456789abcdef0123456789abcdef --policy <policy-id>
185
+ ```
186
+
187
+ `status` lists each policy, whether Quickback owns it, and its latest threshold
188
+ event. `history` with no `--policy` shows configuration changes across the
189
+ account: who made them, with before and after settings (`--cursor` pages, and
190
+ `--limit` accepts up to 100). With `--policy`, it shows that policy's threshold
191
+ events.
192
+
193
+ Keep these states apart:
194
+
195
+ - **Configuration.** Read-back after `apply` confirms the settings Cloudflare
196
+ stored.
197
+ - **Threshold events.** `approaching_limit` (80%) and `limit_reached` (100%)
198
+ record that Cloudflare evaluated the policy. They do not confirm that
199
+ blocking finished or that an email was delivered. If spend jumps past both
200
+ thresholds between evaluations, only the 100% email may arrive.
201
+ - **Enforcement.** An enabled policy is not proof that the product is running,
202
+ and `limit_reached` is not proof that it has stopped.
203
+
204
+ ## After a prolonged Durable Objects block
205
+
206
+ When service returns, by raising the limit, turning it off or reaching the next
207
+ billing period:
208
+
209
+ 1. Check `history --policy <id>` for when the limit was reached.
210
+ 2. Durable Object alarms held for more than seven days during a pause can be
211
+ removed. Reconcile any job, schedule or retry that depends on an alarm, and
212
+ re-arm alarms from your application's own state.
213
+ 3. Check queue consumers and cron-driven work for runs that were skipped while
214
+ Workers were blocked.
215
+ 4. Clients holding WebSockets that stayed open may have missed events. Have
216
+ them resynchronize.
217
+
218
+ ## Workload controls in `quickback.config.ts`
219
+
220
+ Spend policies are account-wide. To limit one Worker, set
221
+ `providers.runtime.config.limits.cpuMs` in the project config. It sets the CPU
222
+ time one invocation may use, emitted as `limits.cpu_ms` (see
223
+ [Runtime options](/configure/providers#runtime-options)). It stops runaway work
224
+ in a single request. It does not cap spend.
@@ -76,6 +76,7 @@ export default defineQueue<ProcessMaterialMessage>({
76
76
  | `messageType` | `string` | Yes | Message type to match (e.g., `'process_material'`) |
77
77
  | `description` | `string` | No | Human-readable description |
78
78
  | `tenant` | `true` | No | Run inside the tenant object named by `message.tenantId` (`tenancy.isolation: 'durable-object'`). See [Tenant databases](/configure/tenant-databases#background-work). |
79
+ | `placement` | `'tenant'` \| `{ partition: '<kind>' }` | No | Which tenant object runs it: the organization object (`'tenant'`, the same as `tenant: true`) or a partition object of the project's partition kind, named by `message.tenantId` + `message.partitionKey`. Must be a literal; conflicts with `tenant: true`. See [Partition jobs](/configure/tenant-databases#partition-jobs). |
79
80
  | `result` | `true` | No | A result job: called from edge code with `callTenantJob(env, tenantId, message, runId)`, which returns the handler's `result`. Needs `tenant: true` and `resultSchema`; never queued. See [Result jobs](/configure/tenant-databases#result-jobs). |
80
81
  | `resultSchema` | `z.object(…)` | With `result` | Validates the returned `result` before it is recorded and returned (at most 256 KiB). `z.object` strips unknown keys; a strict object refuses them; passthrough / loose schemas fail the build. |
81
82
  | `resultTtlSeconds` | number literal | No | Result jobs only: how long the object keeps a call's result so a repeated `runId` replays it. 60 to 604800 (7 days, the default); a short one suits read-only pulls such as exports. See [Result jobs](/configure/tenant-databases#result-jobs). |
@@ -12,6 +12,12 @@ The compiler auto-configures queues when certain features are enabled:
12
12
  | Webhooks | `WEBHOOKS_QUEUE` | Async webhook delivery with retry |
13
13
  | Custom | User-defined | Your own background processing |
14
14
 
15
+ On D1, [durable effects](/platform/database/durable-effects) write a queue
16
+ message's intent in the same transaction as the business writes. They deliver
17
+ it at least once, through a leased dispatcher and consumer admission.
18
+ [Workflows](/platform/workflows) use the same path: the generated consumer
19
+ routes `qb.workflow.*` intents to the workflow dispatcher.
20
+
15
21
  ## Queue Defaults
16
22
 
17
23
  | Setting | Default |
@@ -34,11 +40,23 @@ database: defineDatabase("cloudflare-d1", {
34
40
  maxBatchSize: 5,
35
41
  maxBatchTimeout: 60,
36
42
  maxRetries: 5,
43
+ maxConcurrency: 1, // optional: 1–250
44
+ deadLetterQueue: "my-app-processing-dead-letter", // optional
37
45
  },
38
46
  ],
39
47
  })
40
48
  ```
41
49
 
50
+ `maxConcurrency` (wrangler `max_concurrency`) caps concurrent consumer
51
+ invocations; `1` serializes the queue. `deadLetterQueue` (wrangler
52
+ `dead_letter_queue`) receives messages once `maxRetries` is exhausted; create
53
+ it with `wrangler queues create <name>`. Both are optional and go into the
54
+ queue's `[[queues.consumers]]` block. These are the same consumer settings
55
+ [`bindings.queueConsumers`](/configure/bindings) takes, and the ones to use for
56
+ a queue a [tenant database](/configure/tenant-databases#platform-queues) enqueues to:
57
+ tenant code can only send to the database queues (the primary queue and
58
+ `additionalQueues`).
59
+
42
60
  ## How It Works
43
61
 
44
62
  All queues share a single Cloudflare Workers queue consumer. The consumer inspects each message's `type` field to dispatch to the correct handler:
@@ -52,6 +52,7 @@ The trade-off: any write in the organization changes the version, so unrelated w
52
52
 
53
53
  - **Postgres:** the trigger functions are `SECURITY DEFINER`, owned by `quickback_owner`. The Worker role reads only its active organization's row, or any row on the service lane, and cannot write the table.
54
54
  - **D1:** plain SQLite triggers in the features database.
55
+ - **Database per tenant** ([`tenancy.isolation: 'durable-object'`](/configure/tenant-databases#change-signals-sequences-and-changesets)): each organization's Durable Object holds its own counter, bumped by triggers on its tenant tables; tenant code reads it there. Broadcasts from tenant writes ride the object's outbox and the edge replays them, addressed to that organization.
55
56
  - **Contention:** one row per organization serializes concurrent writes within that organization until each commits.
56
57
  - **Providers:** `cloudflare-d1` and the Postgres providers. Elsewhere the compile fails.
57
58
 
@@ -203,6 +203,19 @@ another tenant's object never reaches that object.
203
203
  hard delete there, call `deleteStorageObjects(env, table, deletedRows)` from
204
204
  `src/lib/storage-keys`. It runs the same prefix check.
205
205
 
206
+ **Finalize.** `db.finalizeUpload(table, id)` loads the row through the firewall
207
+ and answers `{ status, key, uploadId }`. On the edge, `status` is `ready` when
208
+ the object exists and `pending` otherwise.
209
+
210
+ **Tenant tables.** With [database per tenant](/configure/tenant-databases), a
211
+ storage key on a tenant table runs through the tenant file bridge
212
+ (`tenancy.bridges.files`). Actions use the same calls. The object records the
213
+ reservation and every delete intent, and the edge signs, verifies, tombstones
214
+ and deletes. A tenant upload answers `status: 'pending'` and is readable only
215
+ after `db.finalizeUpload` verified its size and type. Keys are namespaced
216
+ `qbt/<project>/<environment>/<organization>/o/…` in the bucket. See
217
+ [Tenant databases → Managed files](/configure/tenant-databases#managed-files).
218
+
206
219
  **What the compiler refuses** (each is a compile error):
207
220
 
208
221
  | Code | Cause |
@@ -113,6 +113,30 @@ For content that doesn't live in a table (previews, external text), call the
113
113
  search service's [`embed()`](/platform/vector/embeddings#generate-embeddings-directly)
114
114
  from an action — it runs under that action's own access rules.
115
115
 
116
+ ## Tenant Databases
117
+
118
+ With [database-per-tenant](/configure/tenant-databases)
119
+ (`tenancy.isolation: 'durable-object'`), a table placed in the organization's
120
+ Durable Object embeds through the **embeddings bridge** instead of the queue
121
+ above. Turn it on with `tenancy.bridges.embeddings: { enabled: true }`; without
122
+ it, `embeddings` on a tenant table is refused.
123
+
124
+ - The object records an index or delete intent in the write's own SQLite
125
+ transaction. The edge Worker, the only holder of `AI` and `VECTORIZE`, embeds
126
+ the text and stores an immutable vector id in the organization's Vectorize
127
+ namespace. A late result never replaces newer content.
128
+ - `GET /api/v1/<resource>?similar=<text>` is the semantic read. It returns only
129
+ rows whose current vector matched, through the resource's firewall, access,
130
+ masking and views. Scores and rejected candidates are never returned.
131
+ - Restore re-indexes in the new generation. Purge deletes the object's vectors
132
+ in bounded steps. Old-generation vectors never match a search.
133
+ - Tenant tables keep vectors only in Vectorize: `embeddingColumn` and
134
+ `metadata` are refused. Source fields must be plain columns. The table's
135
+ firewall must be the organization alone and its read access role-only.
136
+
137
+ See [Tenant databases → Embeddings](/configure/tenant-databases#embeddings) for
138
+ the full contract, models, limits and operator calls.
139
+
116
140
  ## Generated Files
117
141
 
118
142
  When embeddings are configured, the compiler generates:
@@ -235,10 +259,10 @@ export default feature("jobs", {
235
259
  ...q.softDelete(),
236
260
  },
237
261
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
238
- read: {},
239
- create: {},
240
- update: {},
241
- delete: {},
262
+ read: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
263
+ create: { access: { roles: ["owner", "hiring-manager"] } },
264
+ update: { access: { roles: ["owner", "hiring-manager"] } },
265
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
242
266
  });
243
267
  ```
244
268
 
@@ -74,6 +74,23 @@ const vector = await embeddings.jobSimilarity.embed("Text to embed");
74
74
  // Returns: number[] (768 dimensions for bge-base)
75
75
  ```
76
76
 
77
+ ## Semantic Reads on Tenant Tables
78
+
79
+ On a [tenant database](/configure/tenant-databases#embeddings) with the
80
+ embeddings bridge on, the collection route takes `?similar=`:
81
+
82
+ ```bash
83
+ curl "https://api.example.com/api/v1/notes?similar=quarterly%20travel%20budget&limit=10" \
84
+ -H "Authorization: Bearer $TOKEN"
85
+ ```
86
+
87
+ Results come best match first, through the table's firewall, access, masking
88
+ and views. Combine `?similar=` with ordinary filters (`?category=finance`).
89
+ `?search=`, `?total=`, aggregations and cursors are refused beside it. Pages
90
+ use `?offset=` and `?limit=`, up to `tenancy.bridges.embeddings.candidates`
91
+ results in all. Indexing is eventual: a row written a moment ago may not match
92
+ yet.
93
+
77
94
  ## Vectorize Queries
78
95
 
79
96
  If your project uses a Vectorize index, you can query it directly for custom search logic: