@quickback-dev/cli 0.57.0 → 0.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/dist/commands/check.d.ts +24 -0
  2. package/dist/commands/check.d.ts.map +1 -0
  3. package/dist/commands/check.js +111 -0
  4. package/dist/commands/check.js.map +1 -0
  5. package/dist/commands/migrate.d.ts +13 -0
  6. package/dist/commands/migrate.d.ts.map +1 -1
  7. package/dist/commands/migrate.js +232 -0
  8. package/dist/commands/migrate.js.map +1 -1
  9. package/dist/commands/migrate.test.js +109 -0
  10. package/dist/commands/migrate.test.js.map +1 -1
  11. package/dist/docs/content.js +70 -70
  12. package/dist/docs/content.js.map +1 -1
  13. package/dist/index.js +8 -1
  14. package/dist/index.js.map +1 -1
  15. package/dist/skill/docs/changelog.md +42 -1
  16. package/dist/skill/docs/compiler/cloud-compiler/cli.md +46 -2
  17. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +1 -1
  18. package/dist/skill/docs/compiler/cloud-compiler/index.md +60 -4
  19. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +4 -1
  20. package/dist/skill/docs/compiler/definitions/access.md +16 -12
  21. package/dist/skill/docs/compiler/definitions/actions.md +53 -52
  22. package/dist/skill/docs/compiler/definitions/changesets.md +74 -7
  23. package/dist/skill/docs/compiler/definitions/concepts.md +1 -1
  24. package/dist/skill/docs/compiler/definitions/encryption.md +11 -5
  25. package/dist/skill/docs/compiler/definitions/masking.md +23 -6
  26. package/dist/skill/docs/compiler/definitions/permissions.md +22 -23
  27. package/dist/skill/docs/compiler/definitions/read.md +26 -7
  28. package/dist/skill/docs/compiler/definitions/schema.md +48 -4
  29. package/dist/skill/docs/compiler/definitions/sealed-protocol.md +7 -3
  30. package/dist/skill/docs/compiler/index.md +7 -4
  31. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +43 -15
  32. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +17 -5
  33. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +17 -8
  34. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +2 -2
  35. package/dist/skill/docs/stack/cms/index.md +5 -2
  36. package/dist/skill/docs/stack/schedules/index.md +46 -0
  37. package/package.json +1 -1
  38. package/src/skill/docs/changelog.md +42 -1
  39. package/src/skill/docs/compiler/cloud-compiler/cli.md +46 -2
  40. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +1 -1
  41. package/src/skill/docs/compiler/cloud-compiler/index.md +60 -4
  42. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +4 -1
  43. package/src/skill/docs/compiler/definitions/access.md +16 -12
  44. package/src/skill/docs/compiler/definitions/actions.md +53 -52
  45. package/src/skill/docs/compiler/definitions/changesets.md +74 -7
  46. package/src/skill/docs/compiler/definitions/concepts.md +1 -1
  47. package/src/skill/docs/compiler/definitions/encryption.md +11 -5
  48. package/src/skill/docs/compiler/definitions/masking.md +23 -6
  49. package/src/skill/docs/compiler/definitions/permissions.md +22 -23
  50. package/src/skill/docs/compiler/definitions/read.md +26 -7
  51. package/src/skill/docs/compiler/definitions/schema.md +48 -4
  52. package/src/skill/docs/compiler/definitions/sealed-protocol.md +7 -3
  53. package/src/skill/docs/compiler/index.md +7 -4
  54. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +43 -15
  55. package/src/skill/docs/compiler/targets/hono-api/database/index.md +17 -5
  56. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +17 -8
  57. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +2 -2
  58. package/src/skill/docs/stack/cms/index.md +5 -2
  59. package/src/skill/docs/stack/schedules/index.md +46 -0
@@ -46,7 +46,7 @@ Ciphertext cannot be queried, so encrypted columns are **excluded from every que
46
46
  - Never an `embeddings.fields` source (embedding a value ships its plaintext to the model)
47
47
  - The table must carry a `q.scope('organization')` column — keys are per-organization
48
48
  - Text-shaped columns only (v1)
49
- - Database provider must be **Cloudflare D1** or **Neon over HTTP** (the Cloudflare default). Anything else — including Neon's websocket mode — is a compile error, never silently-plaintext output. On Neon, `org_data_keys` lives in the `app` Postgres schema with org-scoped row-level security: a request-scoped connection can read and lazily create exactly its own organization's wrapped-key row; rotation and crypto-shredding are service-role operations.
49
+ - Database provider must be **Cloudflare D1** or **Neon over HTTP/Hyperdrive**. The deprecated Neon WebSocket mode and providers without the key-table plumbing are compile-time refusals, never silently-plaintext output. On Neon, `org_data_keys` lives in the `app` Postgres schema with org-scoped row-level security: a request-scoped connection can read and lazily create exactly its own organization's wrapped-key row; rotation and crypto-shredding are service-role operations.
50
50
 
51
51
  Encrypted columns **may** appear in view projections and responses — they decrypt through the generated prepare path. Masking composes on top as defense-in-depth.
52
52
 
@@ -170,12 +170,18 @@ Sealed values are opaque references at rest, so they're fenced off from every su
170
170
  - The table **must** carry a `q.scope('organization')` column — keys are per-scope.
171
171
  - Reading a sealed column server-side is a **type error**: the column is branded `$type<SealedValue>()`, an opaque non-string, so `db.select()` on it won't typecheck. The server's structural inability to read it is enforced by `tsc`, not convention.
172
172
  - Sealed projects **force-enable** KV-backed JWT revocation (so a revoked reader's in-flight reveal token dies); a project with sealed columns and no KV binding **fails to compile**.
173
- - Database provider must be **Cloudflare D1** or **Neon over HTTP** (the Cloudflare default) — anything else fails to compile. On Neon, the seal/vault tables carry **deny-all row-level security for request connections**: only the worker-internal service-role lane (the generated `/seal/v1` routes, `ctx.seal`, and the sealed write chokepoint) can touch them, and every one of those queries is still explicitly organization-scoped.
173
+ - Database provider must be **Cloudflare D1** or **Neon over HTTP/Hyperdrive** — anything else fails to compile. On Neon, the seal/vault tables carry **deny-all row-level security for request connections**: only the worker-internal service-role lane (the generated `/seal/v1` routes, `ctx.seal`, and the sealed write chokepoint) can touch them, and every one of those queries is still explicitly organization-scoped.
174
174
 
175
175
  ## What this tier does and doesn't claim
176
176
 
177
- The sealed tier protects against **full Worker compromise** — leaked secrets, malicious or buggy server code, a coerced operator. All of them get ciphertext; the keys to read it never exist server-side. What it asks in return:
177
+ The sealed tier protects against **full Worker compromise** — leaked secrets, malicious or buggy server code, a coerced operator. All of them get ciphertext; the keys to read it never exist server-side. Its operating model is explicit:
178
178
 
179
- - **A reveal needs a real second factor.** The vault passphrase (or passkey) is separate from login and never leaves the client. Lose it with no recovery grant and the data is unrecoverable *by design* — that's the guarantee, not a bug. Recovery/escrow and rotation re-granting are roadmap.
179
+ - **A reveal needs a real second factor.** The vault passphrase (or passkey) is separate from login and never leaves the client.
180
+ - **Recovery is opt-in and zero-knowledge.** A key admin can enroll a scope key wrapped under a client-held recovery code through `/seal/v1/recovery/enroll`; `/recovery/use` returns only that opaque wrapped blob. If no recovery is enrolled and every reader loses their factor, the data is unrecoverable by design.
181
+ - **Rotation includes re-granting.** `/rotate` versions the scope key and returns the live-reader worklist and public keys so the key-admin client can wrap and grant the new private key without exposing it to the server.
180
182
  - **No server-side processing.** Your actions can't read, mask, search, or index a sealed value — it's plaintext only in a client that just revealed it. If the server needs to process the field, you want the envelope tier instead.
181
- - **Passkey reveal** verify logic is in place but should be exercised with a real browser/authenticator before production; the passphrase lane is fully round-trip tested.
183
+ - **Passkey rollout check.** The server verification path and nonce-bound
184
+ WebAuthn contract are implemented; before enabling it for a production
185
+ hostname, run the ceremony with that deployment's real browser,
186
+ authenticator, RP ID, and origin. The passphrase lane is fully round-trip
187
+ tested.
@@ -141,9 +141,16 @@ show: {
141
141
 
142
142
  The `'owner'` condition compares against the owner column declared via `q.scope('owner')` (or auto-detected from a `userId` / `ownerId` column). If no owner scope is present, it falls back to `createdBy`.
143
143
 
144
- ### Relationship-roles in masking (v1 limitation)
144
+ ### Relationship-aware field projection
145
145
 
146
- Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }`) are **not yet supported in `show:` clauses**. The compiler refuses to build with a clear error message because async, db-aware mask functions plus a batched relationship matcher (to avoid N+1 on list responses) are required to ship safely — that pipeline has not yet landed. The runtime evaluator fails closed on unrecognized arms, so silent grants are impossible.
146
+ For relationship-specific field visibility, use a named view gated by the
147
+ relationship role. The relationship resolver runs once at the access layer and
148
+ the view projects only the fields that caller may receive.
149
+
150
+ Quickback deliberately does not run per-row database lookups from
151
+ `masking.<field>.show`: doing so would turn list masking into an N+1 query
152
+ pipeline. A relationship-backed `show.roles` entry is therefore a clear
153
+ compile-time refusal, never a silently ignored condition or a broader grant.
147
154
 
148
155
  ### Named gates in masking
149
156
 
@@ -153,12 +160,14 @@ Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }
153
160
  - A gate carrying a **`record:`** predicate is a **compile error** — masking cannot evaluate record conditions, so the record dimension would be silently dropped.
154
161
  - A gate carrying **firewall lanes** is a **compile error** — masking has no firewall array to satisfy, so the gate's row lanes would silently not apply. Reference a who-only rule (or inline the roles) in `show:`, and stamp the firewall gate on the resource's `firewall:` instead.
155
162
 
156
- **Workarounds**, depending on intent:
163
+ **Supported patterns**, depending on intent:
157
164
 
158
165
  - **Gate on BA roles only**: keep masking simple and put the relationship check at the access layer instead — `read.views.<v>.access: { roles: ['guest'] }` returns a curated field projection that excludes the sensitive column entirely for non-staff callers, without involving masking.
159
166
  - **Move the field into a view that's gated by the relationship-role at access**: same pattern — column-level security via field projection rather than per-row masking.
160
167
 
161
- A future async-mask pipeline with batched lookups will lift this limitation; the schema slot is reserved so the v2 add will be non-breaking.
168
+ The schema slot remains reserved for a future batched async-mask pipeline, so
169
+ adding that execution mode will not require changing the surrounding masking
170
+ shape.
162
171
 
163
172
  ## Query Gate (filter / sort / search)
164
173
 
@@ -205,7 +214,9 @@ read: {
205
214
  },
206
215
  ```
207
216
 
208
- `query` replaces the legacy per-capability flags (`filterable`, `searchable`, `sortable`). Setting any of those is rejected at compile time with a migration hint.
217
+ `query` is the unified replacement for the legacy per-capability masking flags
218
+ (`filterable`, `searchable`, `sortable`). If an older definition still uses
219
+ one, the compiler stops with the exact migration to the single role gate.
209
220
 
210
221
  ## Egress protection
211
222
 
@@ -237,7 +248,13 @@ masking: {
237
248
  }
238
249
  ```
239
250
 
240
- `egress` defaults to `'block'` (fail-closed). Note the action scan is a heuristic — it catches the obvious accidental copy (`record.col` straight into a sink) but not values first aliased into another variable, the whole row returned/spread, or a re-fetch via `db.select()`. Treat it as a guardrail against accidents, not a cryptographic boundary; for true secrecy use the [encryption pillar](/compiler/definitions/encryption).
251
+ `egress` defaults to `'block'` (fail-closed). The action scan is an
252
+ accident-prevention layer: it catches direct `record.col` → sink flows without
253
+ pretending to be a whole-program information-flow proof. Aliased values,
254
+ whole-row spreads, and values re-fetched through `db.select()` remain ordinary
255
+ application code. Pair masking with the [encryption
256
+ pillar](/compiler/definitions/encryption) whenever the field needs a
257
+ cryptographic boundary at rest or from the server itself.
241
258
 
242
259
  ## Complete Example
243
260
 
@@ -86,29 +86,28 @@ permission is just the named, reusable spelling.
86
86
  See [Firewall — named permissions](/compiler/definitions/firewall#named-permissions-permission)
87
87
  for how the arm sits inside a firewall.
88
88
 
89
- ## M1 limits
90
-
91
- Permissions are richer than what a firewall can enforce today. The DSL
92
- accepts the full shape so configs are forward-compatible, but a firewall
93
- runs as a SQL `WHERE` clause, so a permission referenced from a firewall
94
- must be **SQL-pushable**. Two cases are rejected at compile time when
95
- referenced from a firewall:
96
-
97
- - **Claim-site leaves.** `{ role }`, `{ scopeRole }`, and `{ pseudoRole }`
98
- are decided from the request's verified claims, not from a row subquery.
99
- A permission containing one of these can't lower to a `WHERE` clause, so
100
- referencing it from a firewall is a compile error. Gate membership on
101
- `read.access` / `crud.*.access` instead, where role checks belong.
102
- - **`not`.** A `not` whose operand resolves to a SQL (relationship) site is
103
- rejected — `NOT IN (subquery)` over a nullable set is the classic
104
- null-trap (a `NULL` row silently passes). It's representable in the DSL for
105
- future claim/runtime sites but errors in a firewall in M1.
106
-
107
- These shapes (`{ role }`, `not`, typed caveats) remain in the DSL because
108
- they're the enforcement surfaces of later milestones (claim-site and runtime
109
- checks). M1 ships the SQL-pushable subset: relationship and `{ permissionRef }`
110
- leaves under `anyOf` / `allOf`. FK-traversal arrows (`{ arrowRef, permission }`)
111
- are now shipped and **are** firewall-pushable — see
89
+ ## Firewall-pushable permission rules
90
+
91
+ A firewall permission compiles all the way down to a SQL `WHERE` expression.
92
+ The production-ready subset includes relationship leaves, composed
93
+ `{ permissionRef }` leaves, and FK-traversal arrows under `anyOf` / `allOf`.
94
+ Those rules run in the database alongside the rest of the row firewall.
95
+
96
+ Two expression shapes belong at a different enforcement site, and the compiler
97
+ routes you there with a build error instead of weakening the policy:
98
+
99
+ - **Claim checks.** `{ role }`, `{ scopeRole }`, and `{ pseudoRole }` are
100
+ decided from verified request claims rather than row subqueries. Put them on
101
+ `read.access` / `crud.*.access`, then keep the permission focused on row
102
+ reachability.
103
+ - **Negated SQL relationships.** `not` over a relationship site is refused
104
+ because nullable `NOT IN (subquery)` semantics create the classic null trap.
105
+ Express the positive relationship set or enforce the exclusion at a runtime
106
+ access site.
107
+
108
+ The wider DSL remains available for permission definitions and future
109
+ enforcement sites, while every firewall reference is checked for SQL
110
+ pushability today. FK-traversal arrows are firewall-pushable; see
112
111
  [Arrows](/compiler/definitions/arrows).
113
112
 
114
113
  The compile-time analyzer flags permissions that can never be satisfied,
@@ -212,13 +212,32 @@ export default defineTable(balanceSnapshots, {
212
212
 
213
213
  ## Aggregate Reads
214
214
 
215
- Reading a parent **with** its owned relations is served today by `defineView`
216
- includes (reverse-FK embedding with per-included-table firewall + masking) and
217
- contract-v2 `?include=` on FK columns. The aggregate-changeset write surface
218
- ([changesets](/compiler/definitions/changesets)) deliberately returns the
219
- **root row only** in v1 — a nested aggregate representation is the phase-2
220
- reader and will land on `?include=` over the `owns` graph, not on the write
221
- response.
215
+ Reading a parent **with** its owned relations rides contract-v2 `?include=`,
216
+ which accepts two kinds of tokens in the same `read.include` allowlist:
217
+
218
+ - **FK columns** (`?include=vendorId`) — forward embeds: the target rows the
219
+ source row points at.
220
+ - **`owns` relation names** (`?include=reactions`) — the phase-2 aggregate
221
+ reader: the changeset root's owned **child rows**, pivoting on the root PK
222
+ and matching the child's declared `fk` column.
223
+
224
+ ```typescript
225
+ export default defineTable(notes, {
226
+ owns: { reactions: { table: 'noteReactions', fk: 'noteId' } },
227
+ read: {
228
+ access: { roles: ['member', 'admin'] },
229
+ include: ['reactions'], // ?include=reactions embeds the children
230
+ },
231
+ });
232
+ ```
233
+
234
+ Both kinds land in the top-level `included` map keyed by the include token,
235
+ then row PK, and both inherit the **target's full security surface** — its
236
+ `read.access` (pre-record-evaluable only, compile-enforced), its firewall
237
+ (ANDed into the child fetch on the caller-claims handle), and its masking.
238
+ `fields[<token>]` sparse projections apply identically. The aggregate-changeset
239
+ write surface ([changesets](/compiler/definitions/changesets)) still returns
240
+ the **root row only** — read the aggregate back with `?include=<relation>`.
222
241
 
223
242
  ## See Also
224
243
 
@@ -352,11 +352,22 @@ These internal tables still participate in the database schema and migrations
352
352
 
353
353
  The compiler automatically injects the four **[audit fields](#audit-fields)** (`createdAt`/`createdBy`/`modifiedAt`/`modifiedBy`), the soft-delete pair (`deletedAt`/`deletedBy`, when soft delete is enabled), and **`organizationId`** into child/junction tables when the parent feature is org-scoped. This ensures cascade soft deletes and scoped queries work correctly without manual column definitions.
354
354
 
355
- > **`id` is currently NOT auto-injected — declare it yourself**
355
+ > **Route keys are handled automatically**
356
356
  >
357
- > Unlike audit fields, the `id` column is your responsibility today. The CRUD/action route generators, FK probing, access checks, and OpenAPI emission all assume every queryable table has a single string-typed `id` column. Tables that omit it — or use a non-`id` single PK (`userId.primaryKey()`) or a compound `primaryKey({ columns: [...] })` constraint — parse fine but produce broken generated code downstream.
357
+ > Quickback gives every route-backed table one stable key. `compiler.injectId`
358
+ > defaults to `'auto'`: a table without a primary key receives an `id` whose
359
+ > generation strategy follows `providers.database.config.generateId`.
358
360
  >
359
- > Use `q.id()` (preferred) or `id: text("id").primaryKey()` / `id: integer("id").primaryKey({ autoIncrement: true })` on every table that participates in routes. For internal tables marked `// @quickback-internal`, the constraint doesn't apply.
361
+ > For a greenfield table with a non-`id` or compound primary key, the compiler
362
+ > preserves that domain uniqueness as a unique index and adds the route `id`.
363
+ > For an already-deployed table where changing the primary key needs a migration,
364
+ > the compile stops with migration guidance instead of emitting broken routes.
365
+ >
366
+ > Use `q.id()` when you want the key visible in authored source. Set
367
+ > `compiler.injectId: false` only when deliberately retaining a custom
368
+ > single-column route key; Quickback resolves that key through schema metadata.
369
+ > Internal `// @quickback-internal` junction tables can keep compound keys because
370
+ > they do not expose CRUD routes.
360
371
 
361
372
 
362
373
  ## Audit Fields
@@ -502,6 +513,38 @@ await db.update(records)
502
513
 
503
514
  You don't set `deletedBy` yourself; the wrapper pairs it with the `deletedAt` signal.
504
515
 
516
+ ### Retention and permanent erasure
517
+
518
+ Soft delete is the recoverable default, not a fixed data-retention policy.
519
+ Quickback leaves the retention window in application code because legal holds,
520
+ customer contracts, and record classes rarely share one universal timer.
521
+
522
+ The platform provides the pieces for an explicit policy:
523
+
524
+ - **Immediate permanent deletion** — configure
525
+ `delete: { mode: 'hard', batch: { mode: 'hard' } }`. Generated hard-delete
526
+ routes record the deletion in the security audit pipeline before removing the
527
+ row.
528
+ - **Time-based purging** — declare a
529
+ [`defineSchedule`](/stack/schedules#retention-and-purge-jobs) job that
530
+ hard-deletes rows whose `deletedAt` is older than your policy cutoff. The
531
+ scheduler emits the Worker cron trigger and runs the same code on D1 or
532
+ Neon.
533
+ - **Aggregate deletion** — use database foreign keys with
534
+ `onDelete: 'cascade'` for same-database ownership, and orchestrate
535
+ cross-database records, R2 objects, and external systems from an explicit
536
+ offboarding action or queued job.
537
+ - **Encrypted data** — envelope-encrypted fields support per-organization
538
+ crypto-shredding by deleting the wrapped DEK. Sealed deployments should
539
+ include their vault grants, recovery records, and key versions in the same
540
+ reviewed offboarding workflow.
541
+
542
+ That makes retention ordinary, version-controlled business logic rather than a
543
+ global platform timer that might erase the wrong class of record. It also keeps
544
+ the compliance claim honest: the schedule and erasure workflow implement your
545
+ policy; enabling soft delete alone does not assert GDPR, HIPAA, or SOC 2
546
+ compliance.
547
+
505
548
  ### Protected system fields
506
549
 
507
550
  The audit and soft-delete columns are always protected from client input, even with `guards: false`:
@@ -773,7 +816,8 @@ export const jobs = pgTable('jobs', {
773
816
  | Feature | SQLite | PostgreSQL |
774
817
  |---------|--------|------------|
775
818
  | Boolean | `integer({ mode: 'boolean' })` | `boolean()` |
776
- | JSON | `text({ mode: 'json' })` | `jsonb()` or `json()` |
819
+ | JSON | `text({ mode: 'json' })` with D1 JSON functions and `->` / `->>` operators | `jsonb()` or `json()` with PostgreSQL JSON indexing |
820
+ | Arrays | Relational child rows or JSON arrays (`json_each`) | Native arrays, relational rows, or JSONB |
777
821
  | Auto-increment | `integer().primaryKey()` | `serial()` |
778
822
  | UUID | `text()` | `uuid()` |
779
823
 
@@ -336,11 +336,15 @@ val plaintext = seal.reveal(session, scope, vaultItemId) /
336
336
 
337
337
  Passkey reveal is the same call as `revealWithPasskey(…, getAssertion)`, where `getAssertion(nonce)` runs the platform WebAuthn ceremony with `challenge = nonce`. Full details, the transport contract, and the conformance harness live in [`apps/seal-sdk/README`](https://github.com/paulstenhouse/quickback-compiler/tree/main/apps/seal-sdk). The SDKs are versioned **with** the compiler in the same repo, so the wire format never drifts from the server you're talking to.
338
338
 
339
- ## Not yet wired
339
+ ## Current lifecycle boundary
340
340
 
341
- Honest gaps, fail-closed until built — a client should not assume these exist:
341
+ The protocol already includes versioned rotation, a reader re-grant worklist,
342
+ grant requests, and recovery-code escrow. Two management conveniences remain
343
+ outside the current contract:
342
344
 
343
345
  - **Content-key re-encryption on rotation** — `/rotate` versions the scope key and re-grants *readers*, and older key versions stay readable, so nothing breaks. But existing sealed *values* keep their content keys wrapped to the old scope key until a client re-seals them; there's no bulk re-encrypt-and-crypto-shred-the-old-version flow yet.
344
346
  - **Audience grants beyond reveal** — `vault_grant` audience reveals are honored at `/reveal`/`/key`, but there's no first-class management surface yet.
345
347
 
346
- These will arrive as additive `:1` routes (no wire-format break) with their own vectors.
348
+ Neither is required for ordinary seal, reveal, grant, revoke, recovery, or key
349
+ rotation flows. Future management routes can be added under the versioned
350
+ protocol without changing the `qbseal:1` wire format.
@@ -28,7 +28,7 @@ quickback/
28
28
 
29
29
  ## The target: Hono on Cloudflare
30
30
 
31
- [Quickback for Hono API](/compiler/targets/hono-api) generates a complete Hono application bundled into a Cloudflare Worker. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL via Hyperdrive.
31
+ [Quickback for Hono API](/compiler/targets/hono-api) generates a complete Hono application bundled into a Cloudflare Worker. Pair with **Cloudflare D1** for managed SQLite or **Neon** for PostgreSQL over HTTP or Hyperdrive.
32
32
 
33
33
  ```typescript
34
34
  providers: {
@@ -44,11 +44,14 @@ providers: {
44
44
  - **[Configuration](/compiler/config)** — `quickback.config.ts`, providers, domains, bindings
45
45
  - **[Getting Started](/compiler/getting-started)** — Templates and full examples
46
46
 
47
- ## The cloud and the CLI
47
+ ## The compiler and the CLI
48
48
 
49
- You don't run the compiler binary locally — it runs as a hosted service:
49
+ `quickback compile` uses the zero-setup hosted compiler by default. Teams with
50
+ restricted-source or build-availability requirements can run the same compiler
51
+ image locally and point the CLI at it:
50
52
 
51
- - **[Cloud Compiler](/compiler/cloud-compiler)** — `compiler.quickback.dev`, CLI, authentication, MCP server for editors
53
+ - **[Hosted and local compilation](/compiler/cloud-compiler)** — one compiler,
54
+ identical generated output, two operational trust boundaries
52
55
  - **[Claude Code Skill](/compiler/claude-code-skill)** — AI-powered authoring assistance
53
56
 
54
57
  ## Development workflow
@@ -1,15 +1,20 @@
1
1
  # D1 Database
2
2
 
3
- Cloudflare D1 is SQLite at the edge. Quickback uses D1 as the primary database for Cloudflare deployments, with a multi-database pattern for separation of concerns.
3
+ Cloudflare D1 is managed, serverless SQLite on Cloudflare's network. It is
4
+ Quickback's zero-configuration default for Cloudflare deployments and a strong
5
+ fit for CRUD-heavy SaaS products, content catalogs, internal tools, and
6
+ workflows that benefit from simple operations.
4
7
 
5
8
  ## What is D1?
6
9
 
7
10
  D1 is Cloudflare's serverless SQL database built on SQLite:
8
11
 
9
- - **Edge-native** - Runs in Cloudflare's global network
10
- - **SQLite compatible** - Use familiar SQL syntax
11
- - **Zero configuration** - No connection strings or pooling
12
- - **Automatic replication** - Read replicas at every edge location
12
+ - **Cloudflare-native** — queried directly from your Worker with no public
13
+ connection string
14
+ - **SQLite SQL** — including D1's supported FTS5, JSON, and math extensions
15
+ - **Zero connection management** — no pool or database server to operate
16
+ - **Managed durability** — built-in disaster recovery, with global read
17
+ replication available through D1 Sessions when a workload needs it
13
18
 
14
19
  ## Multi-Database Pattern
15
20
 
@@ -234,13 +239,36 @@ The `withFirewall` helper:
234
239
  3. **Avoid raw SQL** - Raw SQL bypasses application security; use Drizzle ORM
235
240
  4. **Review custom code** - Manual routes should be code-reviewed for security
236
241
 
237
- ## Limitations
238
-
239
- D1 is built on SQLite, which means:
240
-
241
- - **No stored procedures** - Business logic lives in your Worker
242
- - **Single-writer** - One write connection at a time (reads scale horizontally)
243
- - **Size limits** - 10GB per database (free tier: 500MB)
244
- - **No PostgreSQL extensions** - Use Supabase if you need PostGIS, etc.
245
-
246
- For most applications, these limits are non-issues. D1's edge distribution and zero-config setup outweigh the constraints.
242
+ ## Choose by workload, not by a limitations checklist
243
+
244
+ D1 is more capable than a simple `LIKE`-only store. Cloudflare documents
245
+ [FTS5 full-text search and the JSON
246
+ extension](https://developers.cloudflare.com/d1/sql-api/sql-statements/), and
247
+ D1 supports JSON path extraction, mutation, `->` / `->>` operators, and array
248
+ expansion through
249
+ [`json_each`](https://developers.cloudflare.com/d1/sql-api/query-json/).
250
+ SQLite also supports CTEs and window functions. The important distinction is
251
+ whether your application wants SQLite's model or PostgreSQL's ecosystem.
252
+
253
+ | Need | D1 approach | Choose Neon/Postgres when… |
254
+ |---|---|---|
255
+ | Generated Quickback search | The generated `?search` API uses allowlisted `LIKE` semantics; custom actions can use FTS5 | Search is built around PostgreSQL `tsvector`, language dictionaries, GIN indexes, or an existing Postgres search design |
256
+ | Structured JSON | JSON is stored as text with D1's JSON functions and path operators | You need native `jsonb`, GIN indexing, or extensive JSONB query/update operators |
257
+ | Booleans and arrays | Drizzle maps booleans to SQLite integers; arrays can be modeled relationally or stored/queryable as JSON | Native PostgreSQL booleans/arrays are part of the schema contract |
258
+ | Reporting and aggregation | SQLite CTEs, window functions, joins, and aggregates cover conventional reports | You need Postgres extensions, materialized views, specialized indexes, or a Postgres analytics ecosystem |
259
+ | IDs | `q.id()` uses Quickback's provider-driven generation; SQLite `INTEGER PRIMARY KEY` is also available through Drizzle interop | Native UUID/identity types and database-side defaults are a design requirement |
260
+ | Write profile | A D1 database processes queries serially and is excellent for modest, short writes | The app needs sustained concurrent writes or interactive multi-step transactions |
261
+
262
+ The practical rule is simple:
263
+
264
+ - Start with **D1** for conventional application data, low operational
265
+ overhead, and Cloudflare-native deployment.
266
+ - Start with **Neon/Postgres** when advanced SQL and data types are part of the
267
+ product architecture—not as a workaround after launch. Neon HTTP remains the
268
+ lightweight Cloudflare path; add Hyperdrive only when the application needs
269
+ interactive transactions or connection pooling.
270
+
271
+ Keep Cloudflare's current [D1 platform
272
+ limits](https://developers.cloudflare.com/d1/platform/limits/) in capacity
273
+ planning. Quickback supports both providers, so choosing Postgres for an
274
+ advanced application is a first-class architecture choice.
@@ -1,13 +1,25 @@
1
1
  # Database
2
2
 
3
- The Quickback Stack supports multiple database providers. Choose the one that fits your deployment target.
3
+ Quickback treats D1 and Neon/Postgres as first-class database targets. Choose
4
+ from the application's data model and query profile; the same Quickback
5
+ security definitions compile to either provider.
4
6
 
5
7
  ## Providers
6
8
 
7
- | Provider | Best For | Features |
8
- |----------|----------|----------|
9
- | [Cloudflare D1](/compiler/targets/hono-api/database/d1) | Edge-first apps | SQLite at the edge, zero-latency reads |
10
- | [Neon](/compiler/targets/hono-api/database/neon) | Postgres apps | Serverless Postgres, branching, autoscaling |
9
+ | Provider | Best for | Why choose it |
10
+ |----------|----------|---------------|
11
+ | [Cloudflare D1](/compiler/targets/hono-api/database/d1) | CRUD-heavy SaaS, content catalogs, internal tools, straightforward workflows | Managed SQLite, no connection strings or pooling, Cloudflare-native operations, FTS5 and JSON functions when needed |
12
+ | [Neon](/compiler/targets/hono-api/database/neon) | Data-intensive products and apps designed around PostgreSQL | Native JSONB/arrays, `tsvector` + GIN, PostGIS/extensions, database RLS, advanced indexing and interactive transactions through Hyperdrive |
13
+
14
+ ## Quick decision
15
+
16
+ - Pick **D1** when simple operations and a low-ops Cloudflare deployment are the
17
+ priority.
18
+ - Pick **Neon/Postgres** up front when advanced search, rich data types,
19
+ sustained concurrent writes, Postgres extensions, or database-level RLS are
20
+ product requirements.
21
+ - Hyperdrive is optional: Neon HTTP is the lightweight default on Cloudflare;
22
+ Hyperdrive is the full-featured lane for interactive transactions.
11
23
 
12
24
  ## Getting Started
13
25
 
@@ -1,6 +1,11 @@
1
1
  # Neon
2
2
 
3
- Neon provides serverless PostgreSQL that works with Cloudflare Workers via HTTP connections. Choose Neon when you need PostgreSQL features (JSON operators, full-text search, advanced indexing) or want database-level Row Level Security alongside the generated Hono API.
3
+ Neon provides serverless PostgreSQL for Cloudflare Workers. Choose it when the
4
+ application is designed around PostgreSQL: native JSONB and arrays, `tsvector`
5
+ with GIN indexes, PostGIS or other extensions, sustained concurrent writes, or
6
+ database-level Row Level Security alongside the generated Hono API. D1 also
7
+ supports JSON functions and FTS5; Neon is the choice when the **PostgreSQL
8
+ implementation and ecosystem** are the requirement.
4
9
 
5
10
  ## Why Neon
6
11
 
@@ -722,15 +727,17 @@ precedent — so there is no separate `WEBHOOKS_DB` binding.
722
727
  ## Encryption on Neon
723
728
 
724
729
  The encryption pillar — `.encrypted()` (envelope) and `.sealed()` /
725
- `q.vaultRef()` (sealed) columns — is supported on Neon over HTTP. The
730
+ `q.vaultRef()` (sealed) columns — is supported on Neon over HTTP and
731
+ Hyperdrive. The
726
732
  `org_data_keys` and seal-vault tables fold into the single journaled migration
727
733
  set, and the encryption RLS section rides the journaled RLS migration:
728
734
  `org_data_keys` gets org-scoped RLS (the envelope DEK path needs caller claims),
729
735
  and the vault spine is locked to service-role-only. The seal chokepoints
730
736
  acquire `createServiceDb`.
731
737
 
732
- Both tiers require `connectionMode: 'http'`; under WebSocket mode they are a
733
- fail-closed compile error.
738
+ The deprecated Node/Bun WebSocket mode is a fail-closed compile error for both
739
+ tiers because it cannot provide the request-scoped and service-role handles the
740
+ key tables require.
734
741
 
735
742
  ## Batch transactions
736
743
 
@@ -782,7 +789,7 @@ export default defineAction({
782
789
 
783
790
  Note the `tx.select()…for("update")` form: Drizzle's relational query API
784
791
  (`tx.query.<table>.findFirst`) is [blocked on the scoped
785
- `db`/`tx`](/compiler/definitions/actions#relational-queries-are-blocked-fail-closed)
792
+ `db`/`tx`](/compiler/definitions/actions#scoped-relational-query-safety)
786
793
  because the tenant firewall can't be injected into relational queries. The
787
794
  select builder gives you the same row lock with scope conditions applied
788
795
  automatically.
@@ -948,10 +955,12 @@ automatically.
948
955
  | Factor | Neon | D1 |
949
956
  |--------|------|-----|
950
957
  | SQL dialect | PostgreSQL | SQLite |
958
+ | Search | `tsvector`, language dictionaries, GIN indexes | FTS5 in custom SQL; generated Quickback `?search` uses `LIKE` |
959
+ | Structured data | Native JSONB, arrays, rich Postgres types | JSON text with JSON path/operators; relational or JSON arrays |
951
960
  | Security model | RLS + application-layer | Application-layer only |
952
- | Multi-region | Built-in replication | Single region per database |
953
- | Pricing | Free tier, then usage-based | Free tier, then usage-based |
954
- | Best for | Complex queries, existing Postgres apps | Edge-first, simple schemas |
961
+ | Transactions | HTTP batches; interactive transactions with Hyperdrive | Atomic statements/batches within D1's SQLite execution model |
962
+ | Operations | Neon HTTP is lightweight; Hyperdrive is optional for pooling/interactive transactions | No connection strings or pooling |
963
+ | Best for | Postgres-native, data-intensive, or high-concurrency applications | Cloudflare-native CRUD and conventional application workloads |
955
964
 
956
965
  ## See also
957
966
 
@@ -14,9 +14,9 @@ The generated API returns structured error responses with consistent fields acro
14
14
  | `403` | Forbidden | Access denied (wrong role, condition failed) or firewall blocked it |
15
15
  | `404` | Not Found | Record doesn't exist (or firewall blocked with `errorMode: 'hide'`) |
16
16
  | `409` | Conflict | Unique constraint hit, or a duplicate [`Idempotency-Key`](/stack/api-contract#idempotency-key) still in flight |
17
- | `412` | Precondition Failed | [Changeset](/compiler/definitions/changesets) `If-Match` revision mismatch |
17
+ | `412` | Precondition Failed | `If-Match` revision mismatch — [changesets](/compiler/definitions/changesets) and plain single-record `PATCH`/`PUT`/`DELETE` |
18
18
  | `422` | Unprocessable | `Idempotency-Key` reused with a different request or principal |
19
- | `428` | Precondition Required | `If-Match` sent where no revision exists (root without `updatedAt`, or the POST changeset variant) |
19
+ | `428` | Precondition Required | `If-Match` sent where it can't anchor: no revision column, a batch endpoint (single-resource precondition), or the POST changeset variant |
20
20
  | `429` | Too Many Requests | Rate limit exceeded |
21
21
  | `500` | Internal Error | Uncaught throw — generic body, full error server-side |
22
22
 
@@ -1,8 +1,11 @@
1
1
  # Quickback CMS
2
2
 
3
- > **Early Access**
3
+ > **Available in Early Access**
4
4
  >
5
- > The Quickback CMS is in early access. It works with any Quickback-compiled API that outputs a schema registry. Expect active development and potential changes.
5
+ > The Quickback CMS is available today for any Quickback-compiled API that emits
6
+ > a schema registry. Core schema-driven CRUD, views, actions, access, and masking
7
+ > workflows are ready to use. The CMS is evolving quickly, so review release notes
8
+ > when upgrading projects that depend on customized admin workflows.
6
9
 
7
10
 
8
11
  # Quickback CMS
@@ -72,6 +72,52 @@ execute: async ({ db, withInternalContext }) => {
72
72
 
73
73
  `withInternalContext` builds a context with `internal: true` and `userId: "system:cron-<name>"`, so audited writes made through it are attributable to the schedule (e.g. `system:cron-sweepDigests`) and can reach `roles: ['INTERNAL']`-gated rows. Reach for it whenever the schedule legitimately operates across tenants.
74
74
 
75
+ ## Retention and purge jobs
76
+
77
+ Retention is a strong fit for schedules because the cutoff stays in your
78
+ version-controlled business logic. This example permanently removes records
79
+ 90 days after they were soft-deleted:
80
+
81
+ ```typescript
82
+ // quickback/services/schedules/purgeDeletedRecords.ts
83
+ import { and, isNotNull, lt } from "drizzle-orm";
84
+ import { defineSchedule } from "quickback";
85
+ import { records } from "../../features/records/records";
86
+
87
+ const RETENTION_DAYS = 90;
88
+
89
+ export default defineSchedule({
90
+ name: "purgeDeletedRecords",
91
+ cron: "0 2 * * *",
92
+ description: "Permanently remove records after the recovery window",
93
+ execute: async ({ db, scheduledTime }) => {
94
+ const cutoff = new Date(
95
+ scheduledTime - RETENTION_DAYS * 24 * 60 * 60 * 1000,
96
+ );
97
+
98
+ await db
99
+ .delete(records)
100
+ .where(and(
101
+ isNotNull(records.deletedAt),
102
+ lt(records.deletedAt, cutoff),
103
+ ));
104
+ },
105
+ });
106
+ ```
107
+
108
+ The schedule's plain `db` is intentionally unscoped so a maintenance job can
109
+ operate across tenants and can see rows hidden by the normal
110
+ `deletedAt IS NULL` firewall. Keep the cutoff predicate explicit, process large
111
+ sets in bounded batches, and add the audit/metrics your retention policy
112
+ requires. Use an on-demand admin action or queue workflow for subject- or
113
+ organization-level erasure that also needs to remove R2 objects, auth records,
114
+ or external-provider data.
115
+
116
+ See [Schema → Retention and permanent
117
+ erasure](/compiler/definitions/schema#retention-and-permanent-erasure) for the
118
+ full policy pattern, including hard-delete routes, cascades, and encrypted
119
+ data.
120
+
75
121
  ## Failure isolation
76
122
 
77
123
  The generated `scheduled()` dispatcher runs every schedule whose cron matches `event.cron` concurrently (`Promise.all`), and each handler's errors are caught individually — one failing schedule logs `[Cron] Schedule error` and the others still run to completion. A cron with no registered handler logs `[Cron] No schedule registered` and returns.