@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
@@ -0,0 +1,385 @@
1
+ # Workflows
2
+
3
+ A workflow is a persisted sequence of steps that can sleep for days, wait for
4
+ an approval, and resume after a failure without re-running completed work.
5
+ Quickback compiles each `defineWorkflow` version into a native
6
+ [Cloudflare Workflow](https://developers.cloudflare.com/workflows/) and adds
7
+ four things around it:
8
+
9
+ - **Durable starts and events.** A start, event or control is a row in the run
10
+ registry written in the **same D1 batch** as its
11
+ [durable effect](/platform/database/durable-effects) intent. It exists if
12
+ and only if its dispatch does.
13
+ - **Current authority.** Before **every** step attempt, the initiating actor
14
+ is reloaded from the auth database. A workflow never keeps acting with a
15
+ role the actor has since lost.
16
+ - **Authorized controls.** Start, status, events, cancel, pause, resume and
17
+ retry routes check the caller's current role and the run's owner on every
18
+ call.
19
+ - **Version pinning.** Each version is its own native Workflow. A run finishes
20
+ on the version it started on.
21
+
22
+ A workflow orchestrates work across resources. It is **not** a distributed SQL
23
+ transaction, and it does not make external side effects happen exactly once.
24
+
25
+ ## Enable
26
+
27
+ Workflows need:
28
+
29
+ | Requirement | Why |
30
+ |---|---|
31
+ | Cloudflare runtime | Native Cloudflare Workflows run the steps. |
32
+ | `cloudflare-d1` features database | The run registry and event inbox commit with their intents in one native batch. |
33
+ | [`durableEffects: { enabled: true }`](/platform/database/durable-effects) and a queue | Starts, events and controls are durable intents. |
34
+ | Better Auth `organization` plugin | Every run belongs to an organization actor. |
35
+
36
+ With more than one queue, name the one that carries workflow intents:
37
+
38
+ {/* doc-compile: skip — config fragment; the full defineConfig wrapper is shown in /configure. */}
39
+ ```typescript
40
+ database: defineDatabase("cloudflare-d1", {
41
+ additionalQueues: [
42
+ { name: "my-app-jobs", binding: "JOBS_QUEUE" },
43
+ { name: "my-app-mail", binding: "MAIL_QUEUE" },
44
+ ],
45
+ durableEffects: { enabled: true, workflowQueue: "JOBS_QUEUE" },
46
+ }),
47
+ ```
48
+
49
+ The compiler refuses each missing requirement. There is no degraded mode.
50
+
51
+ ## Define a workflow
52
+
53
+ Put one definition per file under `quickback/services/workflows/`:
54
+
55
+ {/* doc-compile: skip — needs an accounts feature */}
56
+ ```ts title="quickback/services/workflows/onboarding-v1.ts"
57
+ import { z } from "zod";
58
+ import { eq } from "drizzle-orm";
59
+ import { defineWorkflow } from "@quickback/compiler";
60
+ import { accounts } from "../../features/accounts/accounts";
61
+
62
+ export default defineWorkflow({
63
+ name: "onboarding",
64
+ version: 1,
65
+ input: z.object({ accountId: z.string() }),
66
+ result: z.object({ activated: z.boolean() }),
67
+ events: { approval: z.object({ approved: z.boolean() }) },
68
+ access: {
69
+ start: { roles: ["admin"] },
70
+ read: { roles: ["admin", "member"], scope: "organization" },
71
+ },
72
+ run: async ({ input, step }) => {
73
+ await step.run("prepare", async ({ db }) => {
74
+ await db.update(accounts).set({ status: "provisioning" }).where(eq(accounts.id, input.accountId));
75
+ });
76
+ const approval = await step.wait("approval", { timeout: "7 days" });
77
+ await step.run("activate", async ({ db, idempotencyKey }) => {
78
+ await db.update(accounts).set({ status: approval.approved ? "active" : "rejected" }).where(eq(accounts.id, input.accountId));
79
+ // Pass idempotencyKey to external APIs: it is stable across retries.
80
+ });
81
+ return { activated: approval.approved };
82
+ },
83
+ });
84
+ ```
85
+
86
+ Everything that becomes a persisted identity is a literal the compiler checks:
87
+ the `name` (camelCase), the `version` (a positive integer), event names and step
88
+ names. Files starting with `_` are helpers. Any other file in that directory
89
+ must call `defineWorkflow`.
90
+
91
+ | Field | Meaning |
92
+ |---|---|
93
+ | `name`, `version` | Required. Each `(name, version)` is defined once. |
94
+ | `input`, `result` | Zod schemas. Starts are validated against `input`. The return value is validated against `result` before it is stored. |
95
+ | `events` | Zod schema per event name. |
96
+ | `access` | Required. See [Routes and access](#routes-and-access). |
97
+ | `retired` | `true` stops new starts on this version. In-flight runs finish on it. |
98
+ | `retention` | How long a finished run's registry row and result are kept (default `"30 days"`, 1 hour to 365 days). |
99
+ | `authority` | Only `{ mode: "actor" }`, the default. See [Authority](#authority). |
100
+
101
+ ## Steps
102
+
103
+ `run` receives `{ input, step, runId }`. It must destructure its parameter, and
104
+ `step` may only be called directly. Passing, storing or destructuring `step` is
105
+ a compile error, because steps are recorded only through those calls.
106
+
107
+ | Call | Does |
108
+ |---|---|
109
+ | `step.run(name, fn, options?)` | A persisted, side-effecting step. A completed step replays its stored result and never runs again. |
110
+ | `step.sleep(name, duration)` / `step.sleepUntil(name, at)` | A durable sleep. Durations look like `"30 seconds"` or `"7 days"`, or are milliseconds. |
111
+ | `step.wait(event, { key?, timeout? })` | Waits for a declared event and returns its validated payload. |
112
+ | `step.job(name, target, message)` | Calls a tenant [result job](/configure/tenant-databases#result-jobs) in an organization or partition object. |
113
+
114
+ Step names are unique within a version. Repeated work, such as a loop or a
115
+ `map` callback, needs a stable item key: `step.run("charge", fn, { key: invoiceId })`.
116
+ A `run` or `wait` inside a loop without a `key` is a compile error.
117
+
118
+ `fn` receives **fresh handles for each attempt**. Nothing persists between
119
+ attempts except the step's JSON result:
120
+
121
+ | Handle | Is |
122
+ |---|---|
123
+ | `db` | A scoped database for the actor, built exactly like an action's: the same firewall, audit stamps and atomic [`db.batch`](/define/actions/scoped-db#atomic-d1-batches-and-concurrency), including `effects`. |
124
+ | `ctx` | `{ authMethod: "workflow", userId, activeOrgId, roles, orgRole, userRole, workflowRunId }`, reloaded for this attempt. |
125
+ | `env`, `services` | The Worker bindings and services. |
126
+ | `idempotencyKey` | `<runId>:run:<name>[#key]`, stable across attempts. |
127
+ | `attempt` | The 1-based attempt number. |
128
+
129
+ A step's result must be JSON and at most 128 KiB. `undefined` comes back as
130
+ `undefined`.
131
+
132
+ ### Retries and timeouts
133
+
134
+ Native Workflows retries are the **only** retry layer for steps. Quickback adds
135
+ no retry loop of its own.
136
+
137
+ | Option | Default | Bounds |
138
+ |---|---|---|
139
+ | `retries.limit` | `3` | 0–10 |
140
+ | `retries.delay` | `"10 seconds"` | 1 second – 1 hour |
141
+ | `retries.backoff` | `"exponential"` | `constant`, `linear`, `exponential` |
142
+ | `timeout` | `"5 minutes"` | 1 second – 30 minutes |
143
+
144
+ A step can run more than once: after a crash, a timeout, or a lost
145
+ acknowledgement. Make writes idempotent, and pass `idempotencyKey` to external
146
+ APIs. An external request that was already running when a run was cancelled or
147
+ blocked may still complete.
148
+
149
+ ## Authority
150
+
151
+ A run stores its **actor**: the user ID and the organization of the caller who
152
+ started it. It stores no token, session, role snapshot or database handle.
153
+
154
+ Before **every** attempt of a `run` or `job` step, the engine:
155
+
156
+ 1. checks the run is still runnable. A cancelled run, or one being cancelled, stops here;
157
+ 2. reloads the user. The user must exist and not be banned;
158
+ 3. reloads the user's membership in the run's organization;
159
+ 4. expands the membership role through `auth.roleHierarchy`, the same way a request does;
160
+ 5. evaluates `access.execute.roles` (default: `access.start.roles`) with the project's access evaluator.
161
+
162
+ If any check fails, the run becomes **`blocked`** with error `AUTHORITY_REVOKED`,
163
+ and the step does not run. The block is durable and does not retry. The run
164
+ never continues as a system identity or as anyone else. A run that loses
165
+ authority while sleeping or waiting blocks at its next `run` or `job` step.
166
+ Sleeps and waits have no side effects, so they are not checked.
167
+
168
+ [Retry](#controls) resumes a blocked run only when the **original** actor holds
169
+ the execute roles again.
170
+
171
+ Subscription tier roles (`tier_*`) are not re-resolved for steps. A rule that
172
+ names one fails closed. Service authority (`authority: { mode: "service" }`, a
173
+ named, revocable service grant) is not supported yet and is a compile error.
174
+
175
+ ## Routes and access
176
+
177
+ Routes live under the API prefix:
178
+
179
+ | Route | Operation | Response |
180
+ |---|---|---|
181
+ | `POST /api/v1/workflows/<name>/runs` | `start` | `202` + run status. Needs `Idempotency-Key`. |
182
+ | `GET /api/v1/workflows/<name>/runs/<runId>` | `read` | `200` + run status. |
183
+ | `POST …/runs/<runId>/events/<event>` | `signal` | `202`. `Idempotency-Key` is the event ID. |
184
+ | `POST …/runs/<runId>/cancel` | `cancel` | `202` + status. |
185
+ | `POST …/runs/<runId>/pause` · `resume` · `retry` | `control` | `202` + status. |
186
+
187
+ Each `access` rule is `{ roles, scope? }`. `start` is required. `read`, `signal`
188
+ and `cancel` default to `start`, and `control` defaults to `cancel`. `PUBLIC` is
189
+ not allowed.
190
+
191
+ | `scope` | Who can act on a run |
192
+ |---|---|
193
+ | `"actor"` (default) | Only the run's actor, while holding the roles. |
194
+ | `"organization"` | Any member of the run's organization holding the roles. |
195
+
196
+ Every call reloads the caller's membership from the auth database. A cached JWT
197
+ role is not enough. Only a signed-in user with an active organization can call
198
+ these routes. Delegated principals, scope-only principals and share links get
199
+ `403 WORKFLOW_ACTOR_REQUIRED`. A caller without the operation's role on any
200
+ version gets `403`. A run in another organization, a run owned by another actor
201
+ under `"actor"` scope, or an unknown run ID all return the same `404`. Knowing
202
+ a run ID grants nothing.
203
+
204
+ The routes are listed in the generated [OpenAPI](/api/openapi) spec under the
205
+ `Workflows` tag.
206
+
207
+ ## Durable starts and events
208
+
209
+ **Start.** The route validates the input and derives an opaque run ID from the
210
+ project, workflow, organization, actor and `Idempotency-Key`. In **one** D1
211
+ batch it writes the registry row and a `qb.workflow.start` intent. The
212
+ [global idempotency layer](/platform/api-contract#idempotency-key) replays a repeated request with
213
+ the same key. A key reused with a different input is refused.
214
+
215
+ **Dispatch.** The generated queue consumer admits the intent, like every
216
+ durable effect, then creates the native instance **with the run ID as its
217
+ instance ID**. If an earlier create succeeded but its reply was lost, the
218
+ dispatcher finds the instance and does not create a second one. If the Worker
219
+ dies after the commit and before dispatch, the effects sweep delivers the
220
+ intent later.
221
+
222
+ **Events** go to the run's **inbox**: one row per `(runId, eventId)`, written in
223
+ the same batch as a `qb.workflow.event` intent. The native `sendEvent` is only a
224
+ wakeup. A wait first claims the oldest pending matching event from the inbox,
225
+ so an event sent before the run reaches its wait is not lost. Unknown events
226
+ (`400 WORKFLOW_EVENT_UNKNOWN`), invalid payloads, payloads over 64 KiB, events
227
+ for a finished run (`409 WORKFLOW_TERMINAL`) and more than 1,000 unconsumed
228
+ events (`429 WORKFLOW_INBOX_FULL`) are refused.
229
+
230
+ `Idempotency-Key` values are scoped to the caller across the whole API. Use a
231
+ fresh key for every start and every event.
232
+
233
+ ## Status and errors
234
+
235
+ Status responses contain registry facts only:
236
+ `{ runId, workflow, version, status, createdAt, updatedAt, result?, error? }`.
237
+ They never include the persisted input or native internals.
238
+
239
+ | Status | Meaning |
240
+ |---|---|
241
+ | `starting` | Recorded. The native instance may not exist yet. |
242
+ | `running` | The instance exists. |
243
+ | `paused` | Paused on request. |
244
+ | `blocked` | Stopped for review. See `error.code`. |
245
+ | `cancelling` → `cancelled` | Cancellation recorded, then the native instance terminated. |
246
+ | `completed` | Finished. `result` is the validated return value, at most 64 KiB. |
247
+ | `failed` | A step exhausted its retries, a wait timed out, or validation failed. |
248
+
249
+ `error.code` is a stored code: an error's `code` property, or its message when
250
+ that looks like a code (`CARD_DECLINED`). Anything else becomes
251
+ `WORKFLOW_FAILED`, so error messages with user data are never stored.
252
+
253
+ | Code | Status | Cause |
254
+ |---|---|---|
255
+ | `AUTHORITY_REVOKED` | `blocked` | The actor lost the execute roles or the membership. |
256
+ | `VERSION_MISMATCH` / `VERSION_UNAVAILABLE` | `blocked` | The run's version is not the code or binding asked to run it. |
257
+ | `TENANT_*` | `blocked` | A tenant object is permanently unavailable to a `step.job`: purged, archived, restore pending or not provisioned. |
258
+ | `WORKFLOW_RESULT_TOO_LARGE`, `WORKFLOW_STEP_OUTPUT_TOO_LARGE` | `failed` | Size limits. |
259
+
260
+ ## Controls
261
+
262
+ - **Cancel** records `cancelling` and a revision fence **before** it asks the
263
+ platform to terminate the instance. Every new step checks the fence. A step
264
+ already in flight may finish, so the status stays `cancelling` until the
265
+ dispatcher records `cancelled`. Nothing is compensated automatically. Write
266
+ explicit, idempotent cleanup steps when you need them.
267
+ - **Pause** and **resume** apply to `running` and `paused` runs. You can call
268
+ them back to back: each records its status at once, and the dispatcher drives
269
+ the native instance to the latest recorded status, so a pause still in flight
270
+ never undoes the resume that followed it. A paused run keeps its completed
271
+ steps; resume continues from where it stopped.
272
+ - **Retry** applies to `blocked` and `failed` runs. It restarts the native
273
+ instance **from the step that blocked or failed**. Earlier completed steps keep
274
+ their results and do not run again. A run that did not stop at a step, such
275
+ as a version mismatch or a failed result validation, returns
276
+ `409 WORKFLOW_NOT_RETRYABLE`: a restart from the beginning would run completed
277
+ steps again. Start a new run instead.
278
+
279
+ Each control increments the run's revision in the same batch as its intent. The
280
+ dispatcher applies only the latest revision, so a stale or duplicate control
281
+ does nothing.
282
+
283
+ ## Versions
284
+
285
+ Versions are immutable. `onboarding` version 2 is a new file with
286
+ `version: 2`. Each version compiles to its own class, binding and native
287
+ Workflow: `QbWorkflowOnboardingV2`, `QB_WF_ONBOARDING_V2` and
288
+ `<app>-onboarding-v2`. New starts use the highest version that is not retired.
289
+ A run always executes the version recorded in its registry row.
290
+
291
+ Immutable is your contract, not the platform's. Cloudflare does not pin a
292
+ native instance to the Worker deployment it started on. If you edit a deployed
293
+ version's file in place and deploy, its in-flight runs execute the edited code
294
+ from their next step: a sleeping or waiting run wakes on the new deployment.
295
+ An invocation already running may finish on the old code for a short grace
296
+ period first, so one run can mix both. To change steps, add a new version.
297
+
298
+ To retire a version:
299
+
300
+ 1. Set `retired: true` on it and deploy. It accepts no new starts.
301
+ 2. Wait until no run references it:
302
+
303
+ ```bash
304
+ wrangler d1 execute <features-db> --remote --command \
305
+ "SELECT count(*) FROM _quickback_workflow_runs WHERE workflow = 'onboarding' AND version = 1 AND status NOT IN ('completed','failed','cancelled')"
306
+ ```
307
+
308
+ 3. Delete the file.
309
+
310
+ The compiler reads the deployed `wrangler.toml` and refuses to remove a
311
+ version that was deployed without `retired: true`
312
+ (`WORKFLOW_VERSION_REMOVED`). It cannot see the registry, so step 2 is yours to
313
+ check. A run whose version binding is gone is marked `blocked`
314
+ (`VERSION_UNAVAILABLE`). It never runs on another version.
315
+
316
+ ## Tenant and partition steps
317
+
318
+ `step.job` calls a tenant [result job](/configure/tenant-databases#result-jobs)
319
+ using the partition-job destination contract
320
+ ([Partition jobs](/configure/tenant-databases#partition-jobs)):
321
+
322
+ {/* doc-compile: skip — needs a tenant result job */}
323
+ ```ts
324
+ const summary = await step.job("summarize", {
325
+ kind: "partition", organizationId: input.organizationId, partition: "conversation", key: input.conversationId,
326
+ }, { type: "conversation.summary" });
327
+ ```
328
+
329
+ The step first passes the authority check. `target.organizationId` must be the
330
+ run's organization. The job's run ID is `wf:<runId>:job:<name>`, so a retried
331
+ step replays the job's recorded result in that same object. A purged, archived,
332
+ restore-pending or unprovisioned object blocks the run instead of retrying. The
333
+ edge's registry fences apply to workflows exactly as they apply to everything
334
+ else. `step.job` needs `tenancy.isolation: 'durable-object'`.
335
+
336
+ ## Named environments
337
+
338
+ Wrangler does not inherit Workflows into environments. Each
339
+ [environment](/configure/domains#named-environments) target declares its own native
340
+ Workflows under environment-qualified names (`<app>-<env>-onboarding-v2`), and
341
+ keeps its registry in its own features database. Runs never cross targets.
342
+
343
+ ## Data and retention
344
+
345
+ | Stored | Where | Kept |
346
+ |---|---|---|
347
+ | Run identity, version, organization, actor, status, revision, input, result, error code | `_quickback_workflow_runs` (features D1) | Until `retention` after a run finishes. Unfinished runs are never pruned. |
348
+ | Events | `_quickback_workflow_events` | Deleted with their run. |
349
+ | Step results, sleeps, waits | Native Workflow instance state | Cloudflare's instance retention. |
350
+
351
+ The effects sweep cron also deletes expired runs, in batches of 200.
352
+
353
+ ## Limits and guarantees
354
+
355
+ - Delivery is at least once at every boundary: intents, dispatch, events and steps.
356
+ - Nothing is exactly once, and nothing is compensated automatically.
357
+ - Each start, event and control costs one D1 batch, one durable effect and one queue message. Each step attempt adds two auth-database reads and one registry read.
358
+ - Native Workflows limits apply: step count, payload sizes, concurrency and pricing. See [Cloudflare Workflows limits](https://developers.cloudflare.com/workflows/reference/limits/).
359
+
360
+ The generated runtime is tested under Miniflare's local Workflows engine:
361
+ durable starts, the inbox, registry and step state across a process restart,
362
+ pause and resume, revocation and retry, cancellation, and two versions running
363
+ at once. The local engine keeps sleep timers in memory, so after a restart it
364
+ does not wake a sleeping run by itself; the test re-invokes the run through
365
+ pause and resume and checks that completed steps replay. On a deployed
366
+ account (2026-11-19): a run sleeping across a redeploy woke and completed;
367
+ pause, back-to-back pause and resume, cancel, revocation to `blocked`,
368
+ restart-from-step retry, idempotent start and event delivery behaved as
369
+ described here.
370
+
371
+ ## Compile errors
372
+
373
+ | Code | When |
374
+ |---|---|
375
+ | `WORKFLOW_RUNTIME` / `WORKFLOW_DATABASE` | The runtime is not Cloudflare, or the features database is not D1. |
376
+ | `WORKFLOW_DURABLE_EFFECTS_REQUIRED` | `durableEffects` is not enabled. |
377
+ | `WORKFLOW_ORGANIZATIONS_REQUIRED` | The organization plugin is off. |
378
+ | `WORKFLOW_QUEUE` | Several queues and no `workflowQueue`, or an unknown `workflowQueue`. |
379
+ | `WORKFLOW_TENANT_JOB_UNAVAILABLE` | `step.job` without durable-object tenancy. |
380
+ | `WORKFLOW_NAME` / `WORKFLOW_VERSION` / `WORKFLOW_DUPLICATE_VERSION` | Invalid or repeated identity. |
381
+ | `WORKFLOW_ACCESS` / `WORKFLOW_AUTHORITY` / `WORKFLOW_AUTHORITY_SERVICE_UNSUPPORTED` | Invalid policy or authority mode. |
382
+ | `WORKFLOW_STEP_NAME_LITERAL` / `WORKFLOW_STEP_DUPLICATE` / `WORKFLOW_STEP_LOOP_KEY` | A step name that is not a literal, is repeated, or runs in a loop without a key. |
383
+ | `WORKFLOW_STEP_ESCAPES` / `WORKFLOW_STEP_HANDLE` / `WORKFLOW_STEP_EVENT` / `WORKFLOW_STEP_OPTIONS` | Misuse of `step`, an undeclared event, or out-of-bounds options. |
384
+ | `WORKFLOW_NATIVE_NAME` | A native name longer than 64 characters. |
385
+ | `WORKFLOW_VERSION_REMOVED` | A deployed, unretired version was deleted. |
@@ -7,6 +7,33 @@ This page covers the browser flow. For local projects, or anything the browser f
7
7
  > Browser deployment is new. The hosted deploy service sits behind a kill switch, and provisioning is rate-limited to 5 deploys per minute per user — enough to stop a runaway retry loop, not something a normal deploy will ever hit. `quickback deploy` works for everyone today.
8
8
 
9
9
 
10
+ ## If the hosted builder is at capacity
11
+
12
+ When hosted AI generation capacity is exhausted, Start offers the hosted-builder
13
+ waitlist and a way to continue in your own IDE or coding agent. The
14
+ [AI tools setup guide](/tooling/claude-code) covers the Claude Code skill,
15
+ Cursor rules, and the MCP server for compatible agents. Your agent uses its own
16
+ model access.
17
+
18
+ Existing chat history and definitions stay in your browser. If definitions have
19
+ already been created, use **Download your existing definitions** to continue
20
+ locally. The capacity panel pauses new chat submissions; **Try the hosted
21
+ builder again** makes an explicit retry when you want to check availability.
22
+ Other builder errors keep their normal error and retry controls.
23
+
24
+ ## If definition generation stops responding
25
+
26
+ Chat and completed definition writes are saved in your browser. After 45 seconds
27
+ without progress, Start offers **Stop safely** and **Reload saved chat**. A slow
28
+ compile may still be working, so you can also keep waiting. Stopping cancels
29
+ the active request; a normal page reload does not automatically resume it.
30
+
31
+ Use **Continue from saved work** after stopping or reloading an interrupted
32
+ generation. Start keeps completed tool results and removes incomplete calls
33
+ before continuing with your original requirements and existing definitions.
34
+ Incomplete file writes are not treated as saved definitions. Use the same
35
+ browser and keep its site data to retain your saved chat.
36
+
10
37
  ## The three-stage workspace
11
38
 
12
39
  Start keeps authoring, building, and deployment separate:
@@ -17,6 +44,8 @@ Start keeps authoring, building, and deployment separate:
17
44
 
18
45
  All three tabs remain selectable before a build, so the later stages can explain what they need. Editing a definition after a successful build marks Generated Backend **stale** and blocks Cloudflare deployment until you rebuild. This guarantees that the source being deployed matches the revision you inspected.
19
46
 
47
+ A successful build does not verify application behavior. Review custom actions before deployment: a hand-written action without [compiler-applied transition writes](/define/transitions#action-level-extensions) must perform its database write in `execute`. A handler that only returns `{ success: true }` can compile without changing the record. Generated table-level transitions already include the state update.
48
+
20
49
  ## Start from an OpenAPI spec
21
50
 
22
51
  Already have an API? On the empty-chat screen, choose **Start from an OpenAPI spec** and upload an OpenAPI 3 file (JSON or YAML, up to 200 operations). Start converts it in your browser before the agent sees it:
@@ -217,3 +246,25 @@ For ongoing CLI management, keep the same project name and deploy through the sa
217
246
  - The blocked resources listed above.
218
247
 
219
248
  These all work — or will work first — through [`quickback deploy`](/start/deploy).
249
+
250
+
251
+ ### Tested examples and validation checkpoints
252
+
253
+ For a new project matching a complete tested example, Start can copy the current
254
+ canonical files directly into Quickback Definitions and validate them in the
255
+ same operation, before the agent can rewrite them. The files remain ordinary,
256
+ editable project source. Copying refuses to overwrite an existing project and
257
+ does not deploy or create Cloudflare resources. The issue-tracker example includes
258
+ reporter-or-assignee editing, validated assignments, organization-safe references,
259
+ admin workflow transitions, role-specific views, realtime, and sysadmin CMS.
260
+
261
+ Start parses TypeScript writes before saving them, catching syntax errors and
262
+ duplicate imports while retaining the last valid file. This is a syntax check,
263
+ not a generated-project typecheck or a runtime permission test.
264
+
265
+ The agent can validate an incomplete skeleton with
266
+ `compile_project({ intent: "checkpoint" })`. A successful final validation closes
267
+ file edits for that response so the agent can summarize the result rather than
268
+ continue rewriting working files. A subsequent user request can make further
269
+ changes. Definition validation, complete compilation, generated TypeScript, and
270
+ runtime acceptance remain distinct checks.
@@ -18,7 +18,8 @@ cd my-app && quickback deploy
18
18
  - **D1 databases** — auth, features, files, webhooks, and audit databases (whichever your project's features pull in; split-database projects get one entry each)
19
19
  - **KV namespace** — the `KV` binding used for rate limiting and session overflow
20
20
  - **R2 buckets** — file-storage buckets (R2 is referenced by name, so buckets are simply ensured to exist)
21
- 4. **Creates what's missing** — `wrangler d1 create <name>`, `wrangler kv namespace create <BINDING>`, `wrangler r2 bucket create <name>`. Resources are named from your project name exactly the way the compiler names them (`my-app-auth`, `my-app-features`, `my-app-files`, `my-app-KV`, …). If a resource with the expected name already exists in your account, its id is reused instead of creating a duplicate.
21
+ 4. **Creates what's missing** — `wrangler d1 create <name>`, `wrangler kv namespace create <project>-<BINDING>`, `wrangler r2 bucket create <name>`. Resources are named from your project name exactly the way the compiler names them (`my-app-auth`, `my-app-features`, `my-app-files`, `my-app-KV`, …). If a resource with the expected name already exists in your account, its id is reused instead of creating a duplicate.
22
+ Wrangler takes the namespace name literally: the CLI passes the full app-specific title (for example `my-app-KV`), while the Worker binding remains `KV`. A namespace titled only `KV` is not reused for an app-specific resource.
22
23
  5. **Writes ids back into quickback.config.ts** — a surgical, formatting-preserving edit of your `providers.database.config` (and `providers.storage.config` for the KV id when you declare a `cloudflare-kv` storage provider). Comments, indentation, and every other key are left untouched. Works with both authoring styles:
23
24
 
24
25
  ```ts
@@ -131,6 +132,101 @@ quickback migrate data --env production # dry-run pending data migrations
131
132
  See [Check and Push Secrets](/tooling/cli#check-and-push-secrets) and
132
133
  [Data Migrations](/platform/database/data-migrations).
133
134
 
135
+ ## Ephemeral previews
136
+
137
+ `quickback preview` stands up a short-lived, fully isolated copy of the built
138
+ project for review, and tears down exactly what it created:
139
+
140
+ ```bash
141
+ quickback preview plan --name pr-123 # read-only: what would be created or refused
142
+ quickback preview up --name pr-123 --seed preview.seed.json --ttl 72
143
+ quickback preview status
144
+ quickback preview down --name pr-123 # review only
145
+ quickback preview down --name pr-123 --apply # delete
146
+ quickback preview gc --apply # tear down every expired preview
147
+ ```
148
+
149
+ **Template.** A preview copies the selected deployment target — the base
150
+ config, or a named environment with `--env <target>` — from the generated
151
+ `wrangler.toml` and `quickback.deploy.json`. Run `quickback build` first. The
152
+ target must name its account explicitly (`providers.runtime.config.accountId`
153
+ or `environments.<target>.accountId`); every Wrangler call is pinned to it.
154
+
155
+ **Isolation.** Each preview gets its own Worker, its own D1 databases (with the
156
+ project's existing migration history applied), KV namespaces and R2 buckets.
157
+ Bindings that share one D1 database still share one preview database. Durable
158
+ Objects are bound to the preview Worker, so their state is local to it.
159
+ Rate-limit counters get a fresh `namespace_id`. Physical names are
160
+ `qbp-<project-hash>-<generation>[-<binding>]`: a random generation per preview,
161
+ never the preview name. The committed config, `wrangler.toml`, migration
162
+ history and target ids are never edited. The scratch config and ownership
163
+ record live under `.quickback/previews/<name>/`, which ignores itself in git.
164
+
165
+ **Secrets.** Secrets are never copied. `BETTER_AUTH_SECRET` and other
166
+ compiler-generated secrets are minted fresh and sent over stdin after a private
167
+ first upload, so the Worker has no public URL until its secrets exist. When the
168
+ project uses Better Auth, `BETTER_AUTH_URL` is set to the preview's `workers.dev`
169
+ origin and the Worker is redeployed. This happens whether or not `[vars]` sets
170
+ it, because without it Better Auth would reject the preview's own origin. The
171
+ preview is `ready` only after `/health` answers 200.
172
+
173
+ **Synthetic seed.** `--seed <file>` (relative to `quickback/`, which it cannot
174
+ escape) takes `{ "version": 1, "datasets": [{ "binding", "table", "rows" }] }`.
175
+ Tables must be created by that binding's migrations. Framework tables
176
+ (`d1_migrations`, `_`-prefixed) and `AUTH_DB` credential tables are refused.
177
+ Values must be strings, numbers, booleans or null, with up to 1,000 rows per
178
+ dataset and 5,000 in total. Rows go in with `INSERT OR IGNORE`, so give each
179
+ row its primary key and a retried seed stays idempotent. A changed seed is
180
+ refused; tear the preview down and recreate it. Seed data is published on a
181
+ public URL. Never put production data in it.
182
+
183
+ **Supported graph (v1).** A single generated Worker using D1, KV, R2,
184
+ same-Worker Durable Objects and rate limits. `plan` and `up` refuse, before any
185
+ account call:
186
+
187
+ - custom domains or routes: the generated Worker only answers on its configured
188
+ hostnames, so a `workers.dev` preview would 404
189
+ - queue producers or consumers, including generated webhook and outbox consumers
190
+ - cron triggers, service bindings, cross-Worker Durable Objects, Workflows,
191
+ Hyperdrive/Postgres, Vectorize, Workers AI, real email (`send_email`),
192
+ Containers, pipelines, dispatch namespaces, mTLS, Secrets Store, VPC and
193
+ Analytics Engine
194
+ - files, tenant or separate-realtime Workers (multi-Worker topologies)
195
+ - any required secret a human supplies (payments, push, SES, webhooks), and
196
+ Cloudflare owner login
197
+ - any Wrangler table or key Quickback does not classify
198
+
199
+ Nothing is silently removed to make a preview deploy.
200
+
201
+ **Ownership and teardown.** `.quickback/previews/<name>/ledger.json` is the
202
+ only proof of ownership. Intent is recorded before each create and the
203
+ returned id after it. An "already exists" error is a collision, never adoption.
204
+ `down --apply` first tombstones the generation. It then deletes the Worker, R2
205
+ buckets, KV namespaces and D1 databases in that order. Before **each** delete it
206
+ re-checks that the name belongs to this generation and that no generated
207
+ config (any target, any Worker) references the resource. It also checks that
208
+ the live account still maps the name to the recorded id. Production, foreign
209
+ and unconfirmed resources are reported and left in place. A resource that is
210
+ already gone counts as deleted, so `down --apply` is safe to re-run until it
211
+ exits 0. A tombstoned generation is never redeployed. The next `up` mints a new
212
+ generation with new physical names.
213
+
214
+ **Expiry.** `--ttl <hours>` (1–720, default 72) sets `expiresAt`. An expired
215
+ preview is never redeployed. `gc` reviews the expired previews in this
216
+ checkout's records, and `gc --apply` tears them down in batches (`--limit`,
217
+ default 10). It exits non-zero while any cleanup is unresolved, so schedule it.
218
+
219
+ **Recovery.** `up` and `down --apply` resume from the ledger after any failure.
220
+ An R2 bucket that still holds objects fails to delete and stays retryable;
221
+ empty it, then re-run. If a create was interrupted after Cloudflare accepted
222
+ it, the resource is reported as unconfirmed. Verify and delete it by hand, then
223
+ remove its entry from the ledger. Losing the ledger leaks resources but never
224
+ deletes anything, because nothing is deleted without a ledger entry.
225
+
226
+ > Ownership records are local to the checkout. Running previews from CI needs a
227
+ > durable `.quickback/previews/` (artifact or cache) between the up, close and
228
+ > gc jobs; a shared registry and a CI template are not part of v1.
229
+
134
230
  ## Conflicting ids
135
231
 
136
232
  If `quickback.config.ts` already carries a real id for a resource and Cloudflare reports a different one for the same-named resource, `quickback deploy` prints both and stops: