@quickback-dev/cli 0.72.8 → 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 (240) 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 +2 -2
  106. package/dist/skill/docs/configure/index.md +2 -2
  107. package/dist/skill/docs/configure/providers.md +5 -0
  108. package/dist/skill/docs/configure/single-tenant.md +1 -0
  109. package/dist/skill/docs/configure/tenant-databases.md +627 -14
  110. package/dist/skill/docs/define/access.md +26 -0
  111. package/dist/skill/docs/define/actions/defining.md +7 -1
  112. package/dist/skill/docs/define/actions/index.md +5 -0
  113. package/dist/skill/docs/define/actions/scoped-db.md +127 -1
  114. package/dist/skill/docs/define/authoring-basics.md +92 -0
  115. package/dist/skill/docs/define/changesets.md +8 -0
  116. package/dist/skill/docs/define/encryption.md +48 -2
  117. package/dist/skill/docs/define/feature.md +17 -2
  118. package/dist/skill/docs/define/guards.md +11 -3
  119. package/dist/skill/docs/define/index.md +1 -1
  120. package/dist/skill/docs/define/invariants.md +321 -0
  121. package/dist/skill/docs/define/issue-tracker-example.md +225 -0
  122. package/dist/skill/docs/define/masking.md +3 -3
  123. package/dist/skill/docs/define/rate-limit.md +63 -22
  124. package/dist/skill/docs/define/read.md +332 -5
  125. package/dist/skill/docs/define/relationships.md +10 -0
  126. package/dist/skill/docs/define/schema.md +137 -10
  127. package/dist/skill/docs/define/scopes.md +1 -0
  128. package/dist/skill/docs/define/transitions.md +9 -0
  129. package/dist/skill/docs/define/triggers.md +127 -1
  130. package/dist/skill/docs/platform/api-contract/index.md +35 -4
  131. package/dist/skill/docs/platform/auth/api-keys.md +26 -3
  132. package/dist/skill/docs/platform/auth/index.md +5 -2
  133. package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
  134. package/dist/skill/docs/platform/auth/plugins/organization-defaults.md +37 -0
  135. package/dist/skill/docs/platform/auth/using-auth.md +2 -0
  136. package/dist/skill/docs/platform/database/d1.md +73 -1
  137. package/dist/skill/docs/platform/database/durable-effects.md +224 -0
  138. package/dist/skill/docs/platform/database/read-replication.md +9 -0
  139. package/dist/skill/docs/platform/database/recovery.md +292 -0
  140. package/dist/skill/docs/platform/database/using-d1.md +152 -2
  141. package/dist/skill/docs/platform/index.md +1 -0
  142. package/dist/skill/docs/platform/operations/budgets.md +224 -0
  143. package/dist/skill/docs/platform/queues/handlers.md +1 -0
  144. package/dist/skill/docs/platform/queues/index.md +18 -0
  145. package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
  146. package/dist/skill/docs/platform/storage/using-r2.md +13 -0
  147. package/dist/skill/docs/platform/vector/embeddings.md +28 -4
  148. package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
  149. package/dist/skill/docs/platform/workflows/index.md +385 -0
  150. package/dist/skill/docs/start/deploy-browser.md +51 -0
  151. package/dist/skill/docs/start/deploy.md +97 -1
  152. package/dist/skill/docs/tooling/cli.md +117 -0
  153. package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
  154. package/dist/skill/docs/ui/account/customization.md +6 -2
  155. package/dist/skill/docs/ui/account/environment-variables.md +7 -1
  156. package/dist/skill/docs/ui/account/features/admin.md +2 -2
  157. package/dist/skill/docs/ui/account/features/api-keys.md +1 -1
  158. package/dist/skill/docs/ui/account/features/index.md +10 -8
  159. package/dist/skill/docs/ui/account/features/organizations.md +19 -9
  160. package/dist/skill/docs/ui/account/features/passkeys.md +6 -2
  161. package/dist/skill/docs/ui/account/features/sessions.md +2 -2
  162. package/dist/skill/docs/ui/account/index.md +61 -30
  163. package/dist/skill/docs/ui/account/with-quickback.md +1 -1
  164. package/dist/skill/docs/ui/admin/connecting.md +1 -1
  165. package/dist/skill/docs/ui/admin/index.md +1 -1
  166. package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
  167. package/package.json +1 -1
  168. package/src/skill/SKILL.md +9 -3
  169. package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
  170. package/src/skill/docs/api/batch-operations.md +19 -0
  171. package/src/skill/docs/api/caching.md +17 -0
  172. package/src/skill/docs/api/crud.md +9 -0
  173. package/src/skill/docs/api/errors.md +31 -2
  174. package/src/skill/docs/api/query-params.md +6 -0
  175. package/src/skill/docs/changelog/index.md +1 -0
  176. package/src/skill/docs/configure/agents.md +1 -1
  177. package/src/skill/docs/configure/bindings.md +177 -1
  178. package/src/skill/docs/configure/cloudflare-access.md +43 -0
  179. package/src/skill/docs/configure/domains.md +2 -2
  180. package/src/skill/docs/configure/index.md +2 -2
  181. package/src/skill/docs/configure/providers.md +5 -0
  182. package/src/skill/docs/configure/single-tenant.md +1 -0
  183. package/src/skill/docs/configure/tenant-databases.md +627 -14
  184. package/src/skill/docs/define/access.md +26 -0
  185. package/src/skill/docs/define/actions/defining.md +7 -1
  186. package/src/skill/docs/define/actions/index.md +5 -0
  187. package/src/skill/docs/define/actions/scoped-db.md +127 -1
  188. package/src/skill/docs/define/authoring-basics.md +92 -0
  189. package/src/skill/docs/define/changesets.md +8 -0
  190. package/src/skill/docs/define/encryption.md +48 -2
  191. package/src/skill/docs/define/feature.md +17 -2
  192. package/src/skill/docs/define/guards.md +11 -3
  193. package/src/skill/docs/define/index.md +1 -1
  194. package/src/skill/docs/define/invariants.md +321 -0
  195. package/src/skill/docs/define/issue-tracker-example.md +225 -0
  196. package/src/skill/docs/define/masking.md +3 -3
  197. package/src/skill/docs/define/rate-limit.md +63 -22
  198. package/src/skill/docs/define/read.md +332 -5
  199. package/src/skill/docs/define/relationships.md +10 -0
  200. package/src/skill/docs/define/schema.md +137 -10
  201. package/src/skill/docs/define/scopes.md +1 -0
  202. package/src/skill/docs/define/transitions.md +9 -0
  203. package/src/skill/docs/define/triggers.md +127 -1
  204. package/src/skill/docs/platform/api-contract/index.md +35 -4
  205. package/src/skill/docs/platform/auth/api-keys.md +26 -3
  206. package/src/skill/docs/platform/auth/index.md +5 -2
  207. package/src/skill/docs/platform/auth/plugins/index.md +1 -1
  208. package/src/skill/docs/platform/auth/plugins/organization-defaults.md +37 -0
  209. package/src/skill/docs/platform/auth/using-auth.md +2 -0
  210. package/src/skill/docs/platform/database/d1.md +73 -1
  211. package/src/skill/docs/platform/database/durable-effects.md +224 -0
  212. package/src/skill/docs/platform/database/read-replication.md +9 -0
  213. package/src/skill/docs/platform/database/recovery.md +292 -0
  214. package/src/skill/docs/platform/database/using-d1.md +152 -2
  215. package/src/skill/docs/platform/index.md +1 -0
  216. package/src/skill/docs/platform/operations/budgets.md +224 -0
  217. package/src/skill/docs/platform/queues/handlers.md +1 -0
  218. package/src/skill/docs/platform/queues/index.md +18 -0
  219. package/src/skill/docs/platform/realtime/table-changes.md +1 -0
  220. package/src/skill/docs/platform/storage/using-r2.md +13 -0
  221. package/src/skill/docs/platform/vector/embeddings.md +28 -4
  222. package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
  223. package/src/skill/docs/platform/workflows/index.md +385 -0
  224. package/src/skill/docs/start/deploy-browser.md +51 -0
  225. package/src/skill/docs/start/deploy.md +97 -1
  226. package/src/skill/docs/tooling/cli.md +117 -0
  227. package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
  228. package/src/skill/docs/ui/account/customization.md +6 -2
  229. package/src/skill/docs/ui/account/environment-variables.md +7 -1
  230. package/src/skill/docs/ui/account/features/admin.md +2 -2
  231. package/src/skill/docs/ui/account/features/api-keys.md +1 -1
  232. package/src/skill/docs/ui/account/features/index.md +10 -8
  233. package/src/skill/docs/ui/account/features/organizations.md +19 -9
  234. package/src/skill/docs/ui/account/features/passkeys.md +6 -2
  235. package/src/skill/docs/ui/account/features/sessions.md +2 -2
  236. package/src/skill/docs/ui/account/index.md +61 -30
  237. package/src/skill/docs/ui/account/with-quickback.md +1 -1
  238. package/src/skill/docs/ui/admin/connecting.md +1 -1
  239. package/src/skill/docs/ui/admin/index.md +1 -1
  240. package/src/skill/docs/ui/admin/record-layouts.md +3 -3
@@ -166,6 +166,32 @@ read: { access: { roles: ['AUTHENTICATED'] } } // every signed-in caller rea
166
166
  Every empty arm in the project is listed in one compile error, so a project
167
167
  fixes them all in one pass.
168
168
 
169
+ ### Operations without access
170
+
171
+ Every generated CRUD route needs an `access`. A `read`, `create`, `update`,
172
+ `delete` or `put` that mounts a route but declares no `access` is a compile
173
+ error (`ACCESS_REQUIRED`), the same rule actions, transitions and realtime
174
+ deliveries follow. Earlier compilers let such a route admit **any signed-in
175
+ caller**: `delete: { mode: "soft" }` with no access generated a
176
+ `DELETE /:id` (and `DELETE /batch`, with its cascade) that any member of the
177
+ organization could call. The compile error lists every such route in the
178
+ project and says what to write:
179
+
180
+ {/* doc-compile: skip — config fragments, not a compilable project */}
181
+ ```typescript
182
+ // Keep the verb's settings (delete mode, cascades, the changeset gate) and mount no route:
183
+ delete: { mode: "soft", routes: false }
184
+ // Name who may call it:
185
+ delete: { mode: "soft", access: { roles: ["owner", "admin"] } }
186
+ // Keep the old behaviour, on purpose:
187
+ delete: { mode: "soft", access: { roles: ["AUTHENTICATED"] } }
188
+ ```
189
+
190
+ A verb mapped to an action (`create: { action: "…" }`) is exempt: the
191
+ action's own `access`, which every action declares, is AND'd with the
192
+ verb's. Batch routes inherit their verb's access; an explicit batch config
193
+ declared without its verb needs its own.
194
+
169
195
  ## `userRole` vs `roles`
170
196
 
171
197
  `roles` and `userRole` check **two different fields** and are often confused — get this wrong and you'll grant access too broadly.
@@ -82,6 +82,12 @@ export default defineAction({
82
82
  > `quickback/features/*/.quickback/` in `.gitignore` (new projects get this
83
83
  > automatically).
84
84
 
85
+ For a sibling-bound `actions/issues/edit.ts`, import `defineAction` from `../../.quickback/define-action.issues`. That per-table helper
86
+ binds `record` and `whereRecord` to `issues`, not the feature's primary table.
87
+ Import all same-feature table values from `../../.quickback/define-action`.
88
+ See the complete [issue tracker example](/define/issue-tracker-example), which
89
+ compiles and typechecks both helpers together.
90
+
85
91
  For an action that joins or writes a table owned by another feature, keep
86
92
  `defineAction` from the action's own helper and import the other table
87
93
  separately from its feature's generated helper (or generated table module).
@@ -444,7 +450,7 @@ backward paging, nullable keys, joins and totals are not offered.
444
450
  | `bulkVariant` | No | Auto-generate a `POST /:resource/batch/{action}` route alongside the per-record route (record-based actions). See [Bulk Variant](#bulk-variant) |
445
451
  | `webhook` | No | Standalone only. Compile-declared inbound signature verification (`standard-webhooks`, `hmac-sha256`, or `aws-sns`) that runs on the raw bytes **before** parse/access — see [Inbound webhooks](/platform/webhooks/inbound) |
446
452
  | `rawBody` | No | Standalone, non-GET only. Hand `execute` the request body as received (`rawBody: string`, bounded to 1 MiB) for signature schemes the compiler does not model — a per-organization secret stored in the database, a provider with its own canonicalisation. `input` still parses from the same bytes. Actions with `webhook:` receive `rawBody` automatically. The param is typed exactly that way: `rawBody: string` on those actions, absent on every other — see [Per-organization secrets](/platform/webhooks/inbound#per-organization-secrets-verify-in-the-action) |
447
- | `idempotency` | No | `'dedupe'` — PUBLIC-action opt-in for the `Idempotency-Key` header with dedupe-only semantics (duplicate ⇒ `409` reference; the cached body is never served to a second caller). Standalone actions with a **static** path only (a `:param` path is a compile error — the allowlist matches literal request paths) and the action's access must admit `PUBLIC`. Authenticated routes accept the header automatically — see [API contract](/platform/api-contract) |
453
+ | `idempotency` | No | `'required'` — require an `Idempotency-Key` on an authenticated write action (record or standalone), rejecting missing keys with `400 IDEMPOTENCY_KEY_REQUIRED`. GET/HEAD/OPTIONS, PUBLIC access, and per-record bulk variants are rejected. `'dedupe'` — PUBLIC-action opt-in for the `Idempotency-Key` header with dedupe-only semantics (duplicate ⇒ `409` reference; the cached body is never served to a second caller). Standalone actions with a **static** path only (a `:param` path is a compile error — the allowlist matches literal request paths) and the action's access must admit `PUBLIC`. Authenticated routes accept the header automatically — see [API contract](/platform/api-contract) |
448
454
  | `cms` | No | Pass-through metadata blob for CMS surfaces |
449
455
  | `writes` | No | Platform-tier JSON keys this action may change: `{ '<column>' \| '<table>.<column>': ['<key>', …] }`. See [JSON key writes and requires](#json-key-writes-and-requires) |
450
456
  | `requires` | No | A JSON key that must hold before `execute` runs, else 403 `ENTITLEMENT_REQUIRED`: `{ flag: '<key>' }` or `{ json: { column, key, truthy: true \| equals } }`, optionally `from: '<ref as>'`. See [JSON key writes and requires](#json-key-writes-and-requires) |
@@ -169,6 +169,11 @@ update/delete need a record-based action with no `path:`), declares a
169
169
  conflicting `method`, or is already mapped to another verb. `read.action`
170
170
  is not supported.
171
171
 
172
+ In a project with [tenant objects](/configure/tenant-databases), a mapped
173
+ create on a tenant table runs in the organization's object: the edge forwards
174
+ the collection URL, and the tenant Worker serves the action (see
175
+ [Actions at a table route](/configure/tenant-databases#actions-at-a-table-route)).
176
+
172
177
  ### Mapping a verb on an `owns` root
173
178
 
174
179
  A table that declares [`owns`](/define/changesets) can map `create` or `update`
@@ -17,7 +17,12 @@ The firewall is set on the builder when you call `.from()` / `.set()` /
17
17
  `.values()`, `.run()`, `.execute()`, `.prepare()`, and the builder embedded as
18
18
  a subquery (`inArray(col, db.select(...).from(t))`). The firewall-on-write
19
19
  check on an `INSERT` is async, so it runs when the insert executes — on
20
- `await`, on any executor, and ahead of `db.batch([...])`. A `.prepare()`d
20
+ `await` and on any executor. In a D1 `db.batch([...])`, the candidate-row
21
+ firewall is checked in SQL immediately before its insert, inside the same
22
+ transaction. This check sees earlier writes in the batch, including a newly
23
+ created parent or a revoked relationship. A failed check rolls back the entire
24
+ batch with **403 `FIREWALL_WRITE_DENIED`**. Other providers run the check before
25
+ their native batch. A `.prepare()`d
21
26
  insert into a table that needs the check is refused (`FIREWALL_WRITE_CHECK_UNSUPPORTED`):
22
27
  it would run later with nothing to check it.
23
28
 
@@ -139,6 +144,11 @@ export default defineAction({
139
144
  `scopeTo` takes the same three keys as `given`; every value must be a definite
140
145
  string.
141
146
 
147
+ Insert firewall checks see the compiler-stamped audit actor that will be stored,
148
+ including a declared creator lane on a private record before membership rows
149
+ exist. Do not pass `createdBy` to make an insert admissible: the audit wrapper
150
+ owns that field and overwrites supplied actors with the verified caller.
151
+
142
152
  One more source of claims is the route itself. An action under an
143
153
  [`authz.namespaces`](/define/areas#narrow-ctxexposeas-typing) prefix whose
144
154
  lanes are all bulk-grant lanes (`{ roles }`, `{ team }`) only admits callers
@@ -662,6 +672,122 @@ every other read. `amount` must be a positive number (`400 LEDGER_INVALID_AMOUNT
662
672
  otherwise), and `values` may not set the subject, amount or status columns.
663
673
  A missing table or column, or an unknown key, is a compile error.
664
674
 
675
+ ### Atomic D1 batches and concurrency
676
+
677
+ On Cloudflare D1, `db.batch([builder, ...])` executes the supplied statements in
678
+ one native database transaction. A SQL error rolls back every statement,
679
+ including database triggers. Build the statements without awaiting them, then
680
+ await the batch. Results retain the input order and each builder's result type.
681
+
682
+ Quickback applies the scoped firewall, audit stamps, synchronous before hooks,
683
+ and supported encryption preparation. After hooks and change notifications run
684
+ only after the native batch commits. An after-hook failure cannot undo the
685
+ commit: it throws `DB_BATCH_POST_COMMIT_FAILED` with `committed: true` and the
686
+ batch `results`. Do not retry that write as though it rolled back. Batches
687
+ containing SEALED/vault writes are rejected before preparation because that
688
+ storage operation is not part of the same D1 transaction. Envelope-encrypted
689
+ columns are supported; encryption key metadata may be provisioned during
690
+ preparation, before the application-data transaction.
691
+
692
+ An update to a typed JSON column that needs to compare restricted keys with the
693
+ stored row is refused in a D1 batch with `DB_BATCH_GATE_UNSUPPORTED` before any
694
+ writes. That asynchronous check cannot yet join the atomic SQL transaction.
695
+ Updates whose action has permission for every affected key remain supported;
696
+ standalone updates retain their existing key checks.
697
+
698
+ #### Transaction outcomes and recovery
699
+
700
+ | Outcome | Evidence | May mutation code run again? |
701
+ |---|---|---|
702
+ | Rejected before submission | Invalid options/revision token, unsupported builder, or preparation failure before the native call | Only after fixing the rejection; preparation may already have provisioned encryption metadata. |
703
+ | Definitive SQL rollback | `DB_BATCH_CONDITION_FAILED`, `STALE_REVISION`, a batch firewall assertion, `DB_BATCH_ROLLED_BACK`, or a trigger or [invariant](/define/invariants) refusal (422 `TRIGGER_REJECTED`, its code in `details.code`); `details.committed: false` | A bounded retry is allowed after correcting the condition or re-reading. Idempotency marker cleanup must be acknowledged first. |
704
+ | Submitted, outcome unknown | `DB_BATCH_OUTCOME_UNKNOWN`, `details.committed: null`; connection loss or a write deadline is not rollback evidence | No. Keep the same key and reconcile with application state. |
705
+ | Committed, hooks failed | `DB_BATCH_POST_COMMIT_FAILED`, `details.committed: true` | No. Business writes committed. Recover failed post-commit work separately. |
706
+ | Completed replayable response | A matching authenticated request returns the saved response with `Idempotency-Replayed: true` | No. The replay does not execute the handler. |
707
+
708
+ An unrecognized native failure stays outcome-unknown; Quickback only reports
709
+ rollback when it has affirmative SQL constraint/assertion evidence. The original
710
+ cause is retained server-side. Post-commit errors retain caller-ordered `results`
711
+ and failed-hook indices in server code, but HTTP errors expose only the commit
712
+ indicator, never those unmasked rows. A failure while flushing commit notifications
713
+ uses index `-1` because it does not belong to an individual builder.
714
+
715
+ An `Idempotency-Key` receipt is marked before submission. If the worker dies
716
+ between marking and submitting, that receipt still requires reconciliation;
717
+ absence of an acknowledgement is not evidence that retrying is safe. Neither
718
+ lease expiry nor the 24-hour cache sweep removes an unresolved or committed
719
+ atomic receipt. Catching an uncertain batch error and returning a 2xx/4xx does
720
+ not make the operation replayable. A second batch in that request is fenced too.
721
+
722
+ This transaction includes feature-D1 statements, SQL assertions, database
723
+ triggers and the commit marker. It does not include separate AUTH_DB or audit
724
+ stores, vault/R2 operations, external calls, or encryption-key provisioning during
725
+ preparation. After hooks are not a durable delivery mechanism.
726
+
727
+ To make a queue effect commit with the writes, enable
728
+ [durable effects](/platform/database/durable-effects) and pass
729
+ `effects: [{ key, queue, message }]` to the batch. Each intent row joins this
730
+ same transaction, so it is rolled back, unknown or committed exactly as the
731
+ writes are. A repeated key rolls the batch back with `DURABLE_EFFECT_CONFLICT`.
732
+ Delivery is at least once.
733
+
734
+ A batch may require scoped SQL conditions before or after its writes:
735
+
736
+ {/* doc-compile: skip — illustrative fragment inside an action; invoices and paymentLines are application tables imported by the caller. */}
737
+ ```ts
738
+ const results = await db.batch([
739
+ db.update(invoices).set({ status: 'paid' }).where(eq(invoices.id, input.invoiceId)).returning(),
740
+ db.insert(paymentLines).values({ invoiceId: input.invoiceId, amount: input.amount }).returning(),
741
+ ], {
742
+ preconditions: {
743
+ exists: { table: invoices, where: and(eq(invoices.id, input.invoiceId), eq(invoices.status, 'issued')) },
744
+ },
745
+ postconditions: {
746
+ exists: { table: invoices, where: and(eq(invoices.id, input.invoiceId), eq(invoices.status, 'paid')) },
747
+ },
748
+ });
749
+ ```
750
+
751
+ `preconditions` and `postconditions` use the same `exists` / `notExists` probe
752
+ shape as `insertWhere`, including arrays of probes. All probes are ANDed and
753
+ carry their table's firewall. The checks run **inside** the native transaction;
754
+ a failed final check rolls back the preceding writes. They raise
755
+ `DB_BATCH_CONDITION_FAILED` (409), with `details.committed: false` and the
756
+ failed phase. A conditional update matching zero rows is otherwise a valid
757
+ SQL operation: declare a condition when the operation requires a matching row.
758
+
759
+ For decisions made in JavaScript from several reads, enable
760
+ [`changes.counter`](/platform/realtime/table-changes#counter--a-safe-bundle-version-probe) and capture `await db.revision()` **before**
761
+ those reads. Pass the token to the batch:
762
+
763
+ {/* doc-compile: skip — illustrative action fragment; preparePosting/buildPostingStatements are application helpers operating on the same scoped db. */}
764
+ ```ts
765
+ const revision = await db.revision();
766
+ const posting = await preparePosting(db, input);
767
+ const result = await db.batch(buildPostingStatements(db, posting), { revision });
768
+ ```
769
+
770
+ Database triggers advance the active organization's counter for every write
771
+ to its organization-scoped feature tables, including raw SQL, queues, and cron.
772
+ The batch compares that counter before writing. If it changed, the entire batch
773
+ fails with `STALE_REVISION` (409), `details.committed: false`. The application
774
+ can repeat its read-only preparation with a fresh revision and a bounded retry
775
+ policy. Quickback does not automatically repeat application code or external
776
+ side effects.
777
+
778
+ The token is opaque and server-only, bound to the same scoped database handle
779
+ that created it. It cannot be serialized, supplied by the client, or used on
780
+ another handle. Reads must use that handle too: the primary connection or its
781
+ request-scoped D1 session preserves the ordering needed for the check. The
782
+ counter covers **organization-scoped feature data**, not separate AUTH_DB,
783
+ external services, unscoped global tables, or another organization. Include
784
+ explicit SQL conditions for additional same-database dependencies.
785
+
786
+ This API does not make D1 support interactive `db.transaction(async tx => ...)`.
787
+ Reads and JavaScript preparation happen before the batch; SQL constraints and
788
+ conditions validate the result atomically. Ordinary HTTP changesets retain
789
+ their documented `meta.transactional` behavior.
790
+
665
791
  ## Sharing Code Between Actions
666
792
 
667
793
  For Zod schemas, helpers, or constants used across multiple actions in a
@@ -0,0 +1,92 @@
1
+ # Authoring basics
2
+
3
+ Quickback compiles configuration and feature definitions into a backend. Start
4
+ with the layout and security boundaries here, then retrieve only the references
5
+ your app needs. The complete [schema reference](/define/schema) remains available.
6
+
7
+ ## One feature, connected tables
8
+
9
+ ```text
10
+ quickback/
11
+ quickback.config.ts
12
+ features/projects/
13
+ projects.ts # primary table matches feature directory
14
+ issues.ts # sibling table
15
+ issueAssignees.ts # sibling junction
16
+ actions/issues/assign.ts # record action bound to issues
17
+ ```
18
+
19
+ Table files normally default-export `feature("tableName", { columns, ... })`.
20
+ The directory must have its matching primary table. Flat `actions/name.ts`
21
+ binds to that primary table; `actions/issues/name.ts` binds to sibling `issues`.
22
+ An action with an explicit `path` is standalone instead. See [Feature](/define/feature).
23
+
24
+ ## Columns and writes
25
+
26
+ Use `id: q.id()`, `organizationId: q.scope("organization")`, and visible
27
+ `...q.audit()` / `...q.softDelete()` spreads in each soft-deleting table's columns.
28
+ The compiler validates managed columns. Their presence in the schema does not
29
+ mean you supply their values: scoped inserts populate scope and audit values
30
+ from verified context. Provide domain values, not client-chosen tenant or audit
31
+ fields. See [managed columns](/define/schema#how-auto-injection-works-two-layers).
32
+
33
+ Declare createable/updatable domain fields through guards. Protect workflow
34
+ state from ordinary writes and use [transitions](/define/transitions) for
35
+ compiler-owned state changes. Handwritten actions must persist their own domain
36
+ changes unless a documented compiler-applied transition performs them.
37
+
38
+ ## Rows and callers are separate rules
39
+
40
+ The [firewall](/define/firewall) limits which rows may be touched. Organization
41
+ scope derives tenant isolation. [Access](/define/access) decides which caller
42
+ may perform each operation within that boundary. Put boolean `or`/`and` nodes
43
+ on access nodes, not inside a flat `record` condition.
44
+
45
+ For reporter-or-assignee editing, keep both branches. A named
46
+ [relationship role](/define/relationships) requires the same resource column on
47
+ both tables; it does not map `issues.id` to `issueAssignees.issueId`. Use the
48
+ [scoped update action example](/define/issue-tracker-example) for that join. Do not
49
+ replace the requested policy with reporter-only or all-member editing.
50
+
51
+ ## References, parents, and labels
52
+
53
+ Import a sibling FK target with `import projects from "./projects"` in
54
+ `issues.ts`. Declare its column with `.references(() => projects.id, {
55
+ match: { source: "organizationId", target: "organizationId" } })` when both
56
+ rows must share an org. A chain comments → issues → projects is not a cycle.
57
+ See [References](/define/schema#references) and [parent matches](/define/schema#match-a-referenced-rows-parent).
58
+
59
+ The resource `references` map does not create an FK; it accepts legacy target
60
+ strings or explicit diagnostic opt-outs with a reason. It does not accept
61
+ `{ fkTarget, label, via }`. Target `displayColumn` chooses CMS labels.
62
+ Never FK a feature column to Better Auth tables in separate `AUTH_DB`.
63
+
64
+ ## Actions and submitted users
65
+
66
+ A nested `features/projects/actions/issues/assign.ts` uses
67
+ `import { defineAction } from "../../.quickback/define-action.issues"`.
68
+ That helper binds record/whereRecord to issues. Import table values (`issues`, `issueAssignees`) from
69
+ `../../.quickback/define-action`, the primary helper that re-exports all tables. Use scoped `db.select().from()`
70
+ and documented builders, not `db.query`. Record binding or documented `refs`
71
+ loads a target through its firewall. Validate a submitted assignee's membership
72
+ with `getOrgMemberRole(c.get("authDb"), input.userId, ctx.activeOrgId)`; scope
73
+ stamping alone does not check whether the user belongs to that organization.
74
+ See [action authoring](/define/actions/defining) and [scoped DB](/define/actions/scoped-db).
75
+
76
+ CMS entry modes are `cms.access: "member"` or `"sysadmin"`; `"admin"` is not
77
+ a valid mode. Org admins are organization roles, distinct from the platform
78
+ sysadmin. Choose the entry mode explicitly and retain per-table access rules.
79
+
80
+ ## Read next for your requirements
81
+
82
+ - Connected tables and assignment: [issue tracker example](/define/issue-tracker-example).
83
+ - Field types, defaults, uniqueness: [schema](/define/schema).
84
+ - Lifecycle states: [transitions](/define/transitions).
85
+ - Role-specific projections: [views](/define/views).
86
+ - Live updates and audience rules: [realtime](/platform/realtime/using-realtime).
87
+ - Admin UI configuration: [CMS](/ui/admin), then [schema registry](/ui/admin/schema-registry).
88
+
89
+ Validate a connected skeleton first, then add the requested capabilities. Before
90
+ calling the build complete, compare the final files against every requested
91
+ permission and behavior. Compile success establishes valid definitions; runtime
92
+ requests establish that the intended behavior actually works.
@@ -429,6 +429,14 @@ it; `meta.transactional` reports the actual guarantee (same contract as
429
429
  |---|---|---|
430
430
  | postgres / neon (websocket / hyperdrive) / planetscale-postgres (hyperdrive) / libsql / better-sqlite3 / bun-sqlite | `true` | One transaction; any op failure rolls back the root op and every child op |
431
431
  | cloudflare-d1, neon over http (the Cloudflare default) | `false` | Deterministic parent-first **fail-fast**: the first failure stops the changeset; ops already applied stay committed (a consistent prefix — each was independently authorized) |
432
+ | cloudflare-d1 tenant tables ([`tenancy.isolation: 'durable-object'`](/configure/tenant-databases#change-signals-sequences-and-changesets)) | `true` | One `ctx.storage.transaction()` in the organization's Durable Object; any op failure rolls back the whole changeset. Owned tables share the root's placement |
433
+
434
+ [Invariants](/define/invariants) hold inside a changeset like everywhere
435
+ else: an op an invariant refuses fails the changeset with 422
436
+ `TRIGGER_REJECTED`. A [`balanced`](/define/invariants#balanced) root is
437
+ checked when its write unit commits, which is the whole changeset in a tenant
438
+ object. On shared D1 it's each op, so a changeset there can't create an entry
439
+ and its balancing lines in one request. Use an action with `db.batch`.
432
440
 
433
441
  ## Calling it from authored code
434
442
 
@@ -123,13 +123,59 @@ export default feature('integrations', {
123
123
  - **Encrypted at rest** with this envelope tier — same keys, chokepoint, `qbenc:` format, rules, and boot guard as `.encrypted()`.
124
124
  - **Never returned.** The compiler gives the column a `masking` rule of `show: 'never'`, so CRUD, views, realtime, and changesets redact it (`[REDACTED]`; `null` stays `null`, so a client can tell whether one is set) for every role, the owner included. The read path does not even decrypt it. A `masking` entry of your own that would reveal it — `false`, or any `show` other than `'never'` — is a compile error.
125
125
  - **Writable** through create, update, batch, and actions like any column. Clients send plaintext.
126
- - **Readable server-side only through [`ctx.unmask(row, column)`](/define/actions/scoped-db#ctxunmask--reading-a-qsecret-column)** inside an action, which opens it with the row's organization key and records a best-effort audit entry. `ctx.crypto.decrypt` refuses secret columns.
126
+ - **Readable server-side only through [`ctx.unmask(row, column)`](/define/actions/scoped-db#ctxunmask--reading-a-qsecret-column)** inside an action, which opens it with the row's organization key and records a best-effort audit entry, or through [`openSecret`](#opensecret--reading-a-secret-outside-a-request) where there is no request. `ctx.crypto.decrypt` refuses secret columns.
127
127
  - `.sealed()` and `.array()` on a secret are compile errors.
128
128
 
129
129
  | | Stored as | Who reads plaintext |
130
130
  |---|---|---|
131
131
  | `.encrypted()` | envelope ciphertext | allowed roles, through every read path (masking composes on top) |
132
- | `q.secret()` | envelope ciphertext | nobody through a read path; action code through `ctx.unmask` |
132
+ | `q.secret()` | envelope ciphertext | nobody through a read path; action code through `ctx.unmask`; webhooks and queues through `openSecret` |
133
+
134
+ ### `openSecret` — reading a secret outside a request
135
+
136
+ Webhook receivers, queue consumers, schedules and the edge half of a tenant job
137
+ have no request, so no `ctx.unmask`. They read a secret with `openSecret`,
138
+ generated into `src/lib/secrets.ts`:
139
+
140
+ ```ts
141
+ // quickback/services/queues/books-feed.ts (excerpt)
142
+ import { openSecret } from "../../lib/secrets";
143
+
144
+ const key = await openSecret(env, {
145
+ table: "integrationCredentials", // the table's SQL name, as in ctx.unmask's { table, column }
146
+ column: "mercuryBooksApiKey", // the q.secret() column
147
+ organizationId: message.tenantId, // the row must belong to it
148
+ actor: "queue:booksFeed", // user id or service name, recorded as the audit actor
149
+ reason: "Books feed sync", // recorded with the audit row
150
+ });
151
+ if (!key) throw new Error("Books is not connected");
152
+ ```
153
+
154
+ It loads the row scoped to `organizationId` (soft-deleted rows excluded), writes
155
+ a `masked_reveal` row to the security audit log, then decrypts with that
156
+ organization's key. It fails closed: the audit row is written before the key is
157
+ opened, and if the write fails (no `AUDIT_DB`, a failed insert) it throws, so
158
+ no plaintext leaves without an audit row.
159
+
160
+ | Case | Result |
161
+ |---|---|
162
+ | The organization's row exists, column set | plaintext, one audit row (`actor`, `reason`, `table.column`, row id) |
163
+ | Column is null | `null`, no audit row |
164
+ | No `rowId` and the organization has no row | `null`, no audit row |
165
+ | No `rowId` and the organization has several rows | throws `SECRET_ROW_AMBIGUOUS` (409). Pass `rowId`. |
166
+ | `rowId` names no row of that organization (another organization's included) | throws `SECRET_ROW_NOT_FOUND` (404) |
167
+ | Unknown table or column, blank `organizationId`, `actor` or `reason` | throws before any read |
168
+
169
+ Omit `rowId` for a one-row-per-organization table (settings, credentials).
170
+
171
+ `openSecret` is generated when the project has a `q.secret()` table the edge
172
+ Worker serves **and** runs the security audit log (any hard-delete resource,
173
+ `unsafe`, `public` or operator action, or `.sealed()` column turns it on). It
174
+ exists only in the edge Worker. With
175
+ [`tenancy.isolation: 'durable-object'`](/configure/tenant-databases), a tenant
176
+ table's rows live in its object, out of the edge's reach, so only platform
177
+ secret tables are openable, and the tenant Worker has no `openSecret` at all.
178
+ Code running in a tenant object reads its own tenant tables with `ctx.unmask`.
133
179
  | `.sealed()` | client-sealed ciphertext | only a client holding a granted key — the server never can |
134
180
 
135
181
  ## Encrypted columns in tenant tables
@@ -122,7 +122,22 @@ export default feature("episodes", {
122
122
  | `owns` | The composition boundary that turns on atomic parent-plus-children writes | [Changesets](/define/changesets) |
123
123
  | `embeddings` | Vector embeddings generated on insert/update | [Embeddings](/platform/vector/using-embeddings) |
124
124
  | `masking` / `rateLimit` / `namespace` | Field redaction, per-operation caps, a hoisted route prefix + gate | [Masking](/define/masking), [Rate limit](/define/rate-limit), [Areas](/define/areas) |
125
- | `displayColumn` / `defaultSort` / `inputHints` / `layouts` / `references` | How the CMS renders the table — no runtime effect | [CMS](/ui/admin/table-views) |
125
+ | `displayColumn` / `defaultSort` / `inputHints` / `layouts` | How the CMS renders the table — no runtime effect | [CMS](/ui/admin/table-views) |
126
+
127
+ Do not confuse these relationship settings:
128
+
129
+ | Setting | Contract |
130
+ | --- | --- |
131
+ | Column `.references(() => issues.id)` | Declares the feature-table FK and enables generated CRUD referential checks |
132
+ | FK option `match: { source: 'organizationId', target: 'organizationId' }` | Requires source and target rows to share their organization, with database backstops |
133
+ | Target table `displayColumn` | Chooses the CMS label |
134
+ | Resource `references` | Legacy target-name strings or explicit diagnostic opt-outs with a reason; does not create a database FK |
135
+ | `authz.relationships` and named roles | Grants access through domain membership, such as issue assignees |
136
+
137
+ `references: { issueId: { fkTarget, label, via } }` is invalid. Declare the
138
+ column FK, import its target, and configure labels on the target table. See
139
+ [References](/define/schema#references) and the connected
140
+ [issue tracker example](/define/issue-tracker-example).
126
141
 
127
142
  Reach for these before writing an action file: an action is code you maintain,
128
143
  these are declarations the compiler owns. See the full option list in
@@ -198,7 +213,7 @@ For everything action-related — record vs standalone, conflict rules, the gene
198
213
 
199
214
  ## Composition vs reference — `owns`
200
215
 
201
- A schema-level FK (`references:` / `.references()`) says "this row points at
216
+ A schema-level FK (`.references()`) says "this row points at
202
217
  that row." It does **not** say who owns whom. `.references()` may only target
203
218
  another **feature table in the same database** — never Better Auth `users` /
204
219
  `user` / `organization` / `member` (those live in `AUTH_DB`). When a set of child rows has no
@@ -36,9 +36,9 @@ export default defineTable(applications, {
36
36
  },
37
37
  immutable: ["appliedAt", "candidateId", "jobId"],
38
38
  },
39
- create: { /* ... */ },
40
- update: { /* ... */ },
41
- delete: { /* ... */ },
39
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
40
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
41
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
42
42
  });
43
43
  ```
44
44
 
@@ -61,6 +61,14 @@ guards: {
61
61
  }
62
62
  ```
63
63
 
64
+ Guards bind the generated routes. An action writing through its `db` is not
65
+ held by them, which is why `immutable` fields stay writable from actions. When
66
+ a field must not change on **any** write path, declare it as an
67
+ [invariant](/define/invariants): `frozen: { fields: [...] }` for immutable
68
+ columns, `frozen: { when }` for state-locked rows, `appendOnly` for rows that
69
+ never change. The database enforces those for actions, batches, changesets
70
+ and raw SQL too.
71
+
64
72
  ## How It Works
65
73
 
66
74
  | List | What it controls |
@@ -259,7 +259,7 @@ Quickback is **secure by default**. Nothing is accessible until you explicitly a
259
259
  | Layer | Default | What you must do |
260
260
  |-------|---------|------------------|
261
261
  | Firewall | AUTO | Auto-detects from an `organizationId` / `ownerId` / `teamId` column (`userId` is **not** a candidate). Declare `firewall:` explicitly when none matches, when two do, or to opt out with `[{ exception: true }]`. |
262
- | Access | DENIED | Explicitly define `access` rules with roles |
262
+ | Access | DENIED | Explicitly define `access` rules with roles. A generated CRUD route with no `access` is a compile error (`ACCESS_REQUIRED`) — see [Operations without access](/define/access#operations-without-access) |
263
263
  | Guards | LOCKED | Explicitly list `createable`, `updatable` fields |
264
264
  | Rate Limit | ON | Applied to every resource (read 1000/60s, write 200/60s). Override or set `false` to opt out. |
265
265
  | Actions | BLOCKED | Explicitly define `access` for each action |