@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
@@ -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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.57.0",
3
+ "version": "0.58.0",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -2,6 +2,47 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### `?include=<ownsRelation>` — the aggregate reader lands
6
+
7
+ `read.include` now accepts **owns relation names** alongside FK columns:
8
+ `?include=reactions` on a changeset root embeds the aggregate's owned child
9
+ rows (pivot on the root PK, match the child's declared `fk`), landing in the
10
+ same top-level `included` map keyed by include token, then row PK. The child's
11
+ full security surface applies exactly as for FK embeds — pre-record-evaluable
12
+ `read.access` (compile-enforced), firewall ANDed into the fetch on the
13
+ caller-claims handle, masking, and `fields[<token>]` sparse projection. The
14
+ `?fields=` pivot guard follows the direction: an owns embed requires the
15
+ **source PK** in the projection (an FK embed still requires the FK column).
16
+ This closes the changeset design's phase-2 reader — write the aggregate with
17
+ the changeset media type, read it back with `?include=`.
18
+
19
+ ### `afterCommit.reindex` + `afterCommit.notify` — the 06 fast-follows land
20
+
21
+ The two deliveries deferred out of afterCommit v1 now ship, riding the same
22
+ post-commit dispatch seam (best-effort, `waitUntil`, never rolling back the
23
+ committed changeset):
24
+
25
+ - **`reindex: true`** re-enqueues the committed **root row** for embedding
26
+ regeneration on the same at-least-once `EMBEDDINGS_QUEUE` lane the plain
27
+ routes use — after the tx commits, so a rolled-back changeset produces no
28
+ orphan jobs. Fail-closed: requires the root's `embeddings` block; honors
29
+ `onInsert`/`onUpdate: false`; a field-watch array means "always" on the
30
+ aggregate lane. The owns validator's embeddings warning now clears for a
31
+ reindex-declaring root (owned children still warn — root row only).
32
+ - **`notify`** sends a device push via the web-push provider (compile error
33
+ without `push: { provider: 'web-push' }`). The audience is a
34
+ `defineRealtimeDelivery` profile resolved with the **same disclosure
35
+ gates as `broadcast`** — masked columns, `q.stamp` proven identity, and
36
+ child-id enumeration are shared code, not a parallel set. Title/body/url/
37
+ tag are `{key}` templates over a gate-checked payload map; an unmapped
38
+ placeholder is a compile error, a null value at runtime pushes to nobody.
39
+ Scope-keyed deliveries fan to `scope:<room>` subscription tags; user
40
+ deliveries to the user's devices; roles AND-compose.
41
+
42
+ A reindex- or notify-only `afterCommit` no longer requires realtime
43
+ infrastructure — the ws-infra gate now applies only to `broadcast`/`realtime`
44
+ lanes.
45
+
5
46
  ### Typed scoped `db` on every Neon mode + write-side audit forbids
6
47
 
7
48
  The action `db` is now schema-aware on **all** Neon connection modes, not just
@@ -861,7 +902,7 @@ pins binding uniqueness and completeness: every `D1Database` /
861
902
 
862
903
  ### Security: three fail-closed fixes in the generated runtime
863
904
 
864
- - **Scoped `db` blocks Drizzle's relational query API.** `db.query.<table>.findFirst()` / `findMany()` build their SQL outside the scoped wrapper's reach, so they read across organizations. The scoped `db` handed to actions now **throws** on any `db.query.<table>` access (and the Neon hyperdrive typed `db`/`tx` fails `tsc` on it) with directions to `db.select()` (auto-scoped) or an `unsafe: true` action's `unsafeDb.query` with an explicit scope predicate. Handlers that relied on the unscoped pass-through were reading other tenants' rows and must be updated. See [Relational queries are blocked](/compiler/definitions/actions#relational-queries-are-blocked-fail-closed).
905
+ - **Scoped `db` blocks Drizzle's relational query API.** `db.query.<table>.findFirst()` / `findMany()` build their SQL outside the scoped wrapper's reach, so they read across organizations. The scoped `db` handed to actions now **throws** on any `db.query.<table>` access (and the Neon hyperdrive typed `db`/`tx` fails `tsc` on it) with directions to `db.select()` (auto-scoped) or an `unsafe: true` action's `unsafeDb.query` with an explicit scope predicate. Handlers that relied on the unscoped pass-through were reading other tenants' rows and must be updated. See [Scoped relational-query safety](/compiler/definitions/actions#scoped-relational-query-safety).
865
906
  - **`POST /api/v1/token` requires session authentication.** The auth middleware now stamps `ctx.authMethod` (`'session' | 'jwt' | 'api-key' | 'oauth'`), and the token endpoint rejects anything but `'session'` with `401 AUTH_SESSION_REQUIRED`. Pre-fix, a JWT could mint its own replacement — a stolen or revoked token (banned user, removed member, demoted role) could roll a 180s-TTL token forever without re-validating the session.
866
907
  - **Broadcaster DO no longer trusts the `X-Internal-Call` header alone.** Inline-mode `checkAuth` now requires `X-Internal-Secret` to match `BETTER_AUTH_SECRET` (already provisioned; the secret never leaves the worker/DO boundary on a stub call), separate mode compares `ACCESS_TOKEN` constant-time, and every generated internal caller (`lib/realtime.ts` senders, the live-view seq reader, the Better Auth role-change hook) sends the secret. A spoofed header can no longer reach broadcast injection or webhook repointing through any forwarded route.
867
908
 
@@ -112,6 +112,50 @@ ls quickback/.archives/
112
112
 
113
113
  As a safety net, the wipe is **skipped** when the manifest contains zero files for the target directory — that's almost always an upstream compile bug, and we'd rather keep your last working tree than overwrite it with nothing.
114
114
 
115
+ ### Typecheck the Authored Tree
116
+
117
+ ```bash
118
+ quickback check # one-shot; CI-friendly exit codes
119
+ quickback check --watch # re-check on change (tsc --watch)
120
+ ```
121
+
122
+ Runs `tsc` over `quickback/tsconfig.json` — the config the compiler emits on
123
+ every compile, which typechecks the tree you actually edit (actions, lib,
124
+ table files) against the generated `.quickback/` typed helpers. No compile,
125
+ no server: this is your editor's view of the source, on demand.
126
+
127
+ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
128
+ (or a project that has never compiled) exits `2` with a pointer at
129
+ `quickback compile`, which generates the tsconfig and helpers the check
130
+ resolves against. Re-run `quickback compile` after schema changes so the
131
+ helpers track your tables.
132
+
133
+ ### Authored-Source Codemods
134
+
135
+ ```bash
136
+ quickback migrate visible-columns [--dry-run] # declare managed audit columns
137
+ quickback migrate helper-imports [--dry-run] # single typed helper import
138
+ ```
139
+
140
+ `helper-imports` rewrites action files from the legacy pair —
141
+
142
+ ```ts
143
+ import { defineAction } from "../.quickback/define-action";
144
+ import { applications } from "../applications"; // resolves to the authored file
145
+ ```
146
+
147
+ — to the single typed import the helpers are designed for:
148
+
149
+ ```ts
150
+ import { defineAction, applications } from "../.quickback/define-action";
151
+ ```
152
+
153
+ Only provably-safe merges are made: the table import must resolve to the
154
+ helper's own bound table under a name the helper exports. Sibling-table and
155
+ cross-feature imports are left untouched, and unusual shapes (aliases,
156
+ multi-line imports, `import type`) are reported for manual attention instead
157
+ of guessed at.
158
+
115
159
  ### View Documentation
116
160
 
117
161
  ```bash
@@ -299,10 +343,10 @@ Point the CLI to a different compiler (local or custom):
299
343
 
300
344
  ```bash
301
345
  # Use a local compiler
302
- QUICKBACK_API_URL=http://localhost:3020 quickback compile
346
+ QUICKBACK_API_URL=http://localhost:3000 quickback compile
303
347
 
304
348
  # Or export for the session
305
- export QUICKBACK_API_URL=http://localhost:3020
349
+ export QUICKBACK_API_URL=http://localhost:3000
306
350
  quickback compile
307
351
  ```
308
352
 
@@ -68,7 +68,7 @@ Complete compiles (`?complete=true`, the default) always run in the container
68
68
  Point the CLI to a different compiler (local or custom):
69
69
 
70
70
  ```bash
71
- QUICKBACK_API_URL=http://localhost:3020 quickback compile
71
+ QUICKBACK_API_URL=http://localhost:3000 quickback compile
72
72
  ```
73
73
 
74
74
  See [Local Compiler](/compiler/cloud-compiler/local-compiler) for running the compiler locally with Docker.
@@ -1,6 +1,14 @@
1
1
  # Cloud Compiler
2
2
 
3
- Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI uses it to turn your definitions into a complete backend.
3
+ Quickback offers two supported compiler modes. The hosted service at
4
+ `https://compiler.quickback.dev` is the zero-setup default; the same compiler
5
+ image can run locally in Docker when a project needs an entirely local trust
6
+ boundary or compile availability independent of the hosted service.
7
+
8
+ | Mode | Best for | Source path |
9
+ |---|---|---|
10
+ | Hosted compiler | Fast onboarding, CI without compiler infrastructure, automatic compiler updates | Authenticated HTTPS to `compiler.quickback.dev` |
11
+ | Local compiler | Restricted-source environments, offline development, self-managed availability | Loopback-only Docker + `QUICKBACK_API_URL` |
4
12
 
5
13
  ## How It Works
6
14
 
@@ -11,8 +19,8 @@ Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI
11
19
  │ │ │ │
12
20
  │ Sends: │ │ Returns: │
13
21
  │ - config │ │ - Hono routes │
14
- │ - features │◀────────│ - Drizzle migrations │
15
- │ - meta │ │ - TypeScript SDK │
22
+ │ - source │◀────────│ - Drizzle migrations │
23
+ │ - DB meta │ │ - TypeScript SDK │
16
24
  └──────────────┘ └──────────────────────┘
17
25
  ```
18
26
 
@@ -21,6 +29,54 @@ Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI
21
29
  3. The compiler generates all backend files (routes, migrations, SDK, OpenAPI spec).
22
30
  4. The CLI writes the generated files to your project.
23
31
 
32
+ ## What the hosted compiler receives
33
+
34
+ The compile payload contains the source material needed to generate the
35
+ backend: Quickback config, feature/table definitions, authored actions and
36
+ selected project-local helpers, plus Quickback-owned Drizzle migration metadata
37
+ on incremental compiles.
38
+
39
+ That material describes application structure and behavior; it is not the
40
+ production dataset. The compiler does **not** connect to your deployed database
41
+ or receive customer rows, uploaded files, or live Worker environment values.
42
+ Keep runtime credentials in Worker secrets and reference their environment
43
+ variable names from config—do not hard-code secret values in source sent to
44
+ either compiler mode.
45
+
46
+ For most applications, schema names and access declarations are ordinary source
47
+ metadata rather than the business's core proprietary dataset. Authored action
48
+ and helper code can still contain proprietary business logic, so organizations
49
+ whose policy classifies that source as restricted can use the local compiler
50
+ without changing their definitions or generated output.
51
+
52
+ ## Processing, analytics, and AI use
53
+
54
+ - Compile payloads are processed for the request. Full compiles use an isolated
55
+ temporary work directory that is deleted in a `finally` cleanup on success or
56
+ failure; validation compiles run in memory.
57
+ - Quickback does not retain request source or generated output as a project
58
+ artifact on the compiler service.
59
+ - The hosted edge records operational analytics: user/organization identifiers,
60
+ app and feature names, provider/service choices, status, counts, timing, and
61
+ compiler version. It does **not** write source bodies or generated file
62
+ contents to analytics. These metrics use Cloudflare Workers Analytics Engine,
63
+ whose documented retention window is currently [three
64
+ months](https://developers.cloudflare.com/analytics/analytics-engine/limits/#data-retention).
65
+ - The compile path does not invoke an AI model, and compile payloads or outputs
66
+ are not used to train models.
67
+
68
+ If your policy requires that source never cross a network boundary, use the
69
+ [local compiler](/compiler/cloud-compiler/local-compiler). It uses the same
70
+ Docker image and output path as hosted compilation.
71
+
72
+ ## Availability
73
+
74
+ Hosted compilation removes compiler setup from normal development. It is not a
75
+ required runtime dependency: a deployed Quickback backend continues operating
76
+ without the compiler, and builds can switch to the local compiler by setting
77
+ `QUICKBACK_API_URL=http://localhost:3000`. Teams with strict build-availability
78
+ requirements can keep the local Docker path in CI or their release runbook.
79
+
24
80
  ## Quick Start
25
81
 
26
82
  ```bash
@@ -62,4 +118,4 @@ No extra configuration needed — the CLI handles this automatically.
62
118
  - [Authentication](/compiler/cloud-compiler/authentication) — Login flow and API keys
63
119
  - [Endpoints](/compiler/cloud-compiler/endpoints) — Compiler API reference
64
120
  - [Troubleshooting](/compiler/cloud-compiler/troubleshooting) — Common issues
65
- - [Local Compiler](/compiler/cloud-compiler/local-compiler) — Run the compiler locally
121
+ - [Local Compiler](/compiler/cloud-compiler/local-compiler) — Use the same compiler image locally or in restricted-source environments
@@ -1,6 +1,9 @@
1
1
  # Local Compiler
2
2
 
3
- Run the Quickback compiler locally using Docker. The local compiler uses the exact same Docker image as the cloud compiler, ensuring identical behavior — including SPA builds with correct environment variables.
3
+ Run the Quickback compiler locally using Docker. This is a fully supported
4
+ compiler mode, not a reduced fallback: it uses the exact same Docker image as
5
+ the hosted compiler and produces the same backend, migrations, SDKs, and SPA
6
+ builds while keeping compile source on the local machine.
4
7
 
5
8
  ## Prerequisites
6
9
 
@@ -501,25 +501,28 @@ export default defineConfig({
501
501
 
502
502
  Resource definitions reference declared roles by name in `roles: [...]` arrays exactly like BA roles or pseudo-roles. The compiler rewrites the access tree at build time so the runtime route does an inline relationship lookup against the declared table.
503
503
 
504
- **Today (v1) this works on:**
504
+ #### Supported relationship-role surfaces
505
505
 
506
506
  | Surface | Status | Notes |
507
507
  |---|---|---|
508
508
  | `firewall:` `via:` predicate | ✓ Supported | Subquery composes as outermost AND |
509
509
  | `crud.*.access` `roles: ['guest']` | ✓ Supported | Inline async lookup per request |
510
510
  | `read.access` / `read.views.*.access` `roles: ['guest']` | ✓ Supported | Same inline path |
511
- | `masking.<field>.show` `roles: ['guest']` | ⚠ Refused at compile | v1 limitation — async/batched mask functions deferred |
512
- | **Standalone** `actions.<name>.access` `roles: ['guest']` | ✓ Supported (v0.19+) | Inline gate; surface must expose `resource.column` as path param or input field |
513
- | **Record-based** `actions.<name>.access` `roles: ['guest']` | ⚠ Fail-closed at runtime | Runtime helper denies; inline emission is a planned follow-up. Use `firewall: { exception: true }` or move the check into `execute()` until then |
514
-
515
- For the surfaces that are not yet supported, the compiler refuses at build time with a clear error pointing to a workaround. The runtime evaluator fails closed on relationship arms regardless, so silent grants are impossible.
511
+ | **Standalone** `actions.<name>.access` `roles: ['guest']` | ✓ Supported | Inline gate; the surface exposes `resource.column` as a path param or input field |
512
+ | **Record-based** `actions.<name>.access` `roles: ['guest']` | ✓ Supported | Inline lookup uses the already-loaded, firewalled record |
513
+ | Namespace `via` lanes | ✓ Supported | Hoisted middleware resolves once and can hydrate `ctx.<exposeAs>` |
514
+ | `masking.<field>.show` `roles: ['guest']` | Build-time refusal | Use a relationship-gated view for field projection; per-row async masking is not approximated |
515
+
516
+ Relationship roles are therefore available across CRUD, reads, standalone
517
+ actions, record-based actions, and namespace mounts. Masking is the one
518
+ different execution surface: list masking must stay synchronous and batched, so
519
+ the compiler rejects a relationship-bearing `masking.show` rule and points to a
520
+ relationship-gated view instead. It never drops the relationship arm or turns
521
+ it into a broader role grant.
516
522
 
517
523
  ### Standalone actions: surface keys and `loads` / `exposeAs` (v0.19+)
518
524
 
519
- When a standalone action's `access.roles` references a relationship-role, the compiler emits a runtime gate between input validation and `execute()`. The gate reads the relationship's `resource.column` value from the action surface — either a path parameter (`:eventId`) or an input field (`input.eventId`). If neither is present, the compiler:
520
-
521
- - **v0.19** — emits a `[quickback:authz]` warning and skips resolver emission. The action's own hand-rolled gate (if any) keeps the route working at runtime.
522
- - **v0.20** — hard compile error. Set `firewall: { exception: true }` to opt out (cross-tenant/admin routes only).
525
+ When a standalone action's `access.roles` references a relationship-role, the compiler emits a runtime gate between input validation and `execute()`. The gate reads the relationship's `resource.column` value from the action surface — either a path parameter (`:eventId`) or an input field (`input.eventId`). If neither is present, the current compiler stops with a clear build error; an action can never ship with a relationship rule it has no key to evaluate.
523
526
 
524
527
  Pair the relationship with `loads` + `exposeAs` to hydrate the loaded resource onto `ctx`:
525
528
 
@@ -617,7 +620,7 @@ defineAction({
617
620
  path: '/admin/cross-tenant-report',
618
621
  firewall: { exception: true },
619
622
  unsafe: { reason: 'cross-tenant audit', adminOnly: true, targetScope: 'all' },
620
- access: { roles: ['ADMIN'] },
623
+ access: { roles: ['SYSADMIN'] },
621
624
  execute: async ({ unsafeDb, ctx }) => { /* cross-org query */ },
622
625
  });
623
626
  ```
@@ -731,7 +734,8 @@ The validator and resolver reject:
731
734
  - Relationship table with `firewall: { exception: true }` (would let cross-tenant grants slip through).
732
735
  - `lowering: 'session'` (reserved for v2 — staleness/invalidation ergonomics not yet shipped).
733
736
  - `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
734
- - Relationship-roles in `masking.show` / `actions.access` (deferred surfaces — see the table above).
737
+ - Relationship-backed rules in `masking.show` (use a relationship-gated view
738
+ for field projection; action access is fully supported).
735
739
 
736
740
  ## Namespace mounts (hoisted relationship middleware)
737
741
 
@@ -689,7 +689,12 @@ access: async (ctx, record) => {
689
689
 
690
690
  ### Relationship-roles in actions
691
691
 
692
- **v0.19+** — standalone actions now support relationship-roles in `access.roles` directly. Declare the relationship under `authz.relationships` with optional `loads` / `exposeAs` for ctx hydration, and reference the role by name on the action:
692
+ Both standalone and record-based actions support relationship roles directly in
693
+ `access.roles`. Declare the relationship under `authz.relationships`, name it
694
+ under `authz.roles`, and use that name like any organization or pseudo-role.
695
+
696
+ For a standalone action, optional `loads` / `exposeAs` fields can hydrate the
697
+ matched resource onto `ctx`:
693
698
 
694
699
  ```ts
695
700
  // quickback.config.ts
@@ -719,49 +724,40 @@ export default defineAction({
719
724
  });
720
725
  ```
721
726
 
722
- The action's surface (path params + input fields) must expose the relationship's `resource.column`. At v0.19 a missing key emits a `[quickback:authz]` warning and skips resolver emission; at v0.20 it becomes a compile error. See [Access — standalone actions](/compiler/definitions/access#standalone-actions-surface-keys-and-loads--exposeas-v019) for the full mechanism.
723
-
724
- **Record-based actions** are NOT yet supported — the runtime evaluator fail-closes (403) on relationship arms reached without an inline gate. Until inline emission for record-based actions lands, either:
725
-
726
- - Set `firewall: { exception: true }` on the action and gate manually in `execute()`, OR
727
- - Apply the relationship at the resource's firewall layer (worked example below).
727
+ The standalone action's surface (path params + input fields) must expose the
728
+ relationship's `resource.column`. A missing key is a compile error, so the
729
+ resolver can never be skipped silently. See [Access — standalone
730
+ actions](/compiler/definitions/access#standalone-actions-surface-keys-and-loads--exposeas-v019)
731
+ for the full mechanism.
728
732
 
729
- **Resource-layer workaround for record-based actions**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
733
+ For a record-based action, Quickback already has the firewalled record in
734
+ scope. It emits an inline relationship match against that record before
735
+ `execute()` runs:
730
736
 
731
737
  ```typescript
732
- // quickback.config.ts
733
- authz: {
734
- relationships: {
735
- guestOf: {
736
- from: 'event_guests',
737
- subject: { column: 'userId', equals: 'ctx.userId' },
738
- resource: { column: 'eventId' },
739
- where: { status: 'confirmed' },
740
- },
738
+ // features/sessions/actions/comment.ts
739
+ export default defineAction({
740
+ input: z.object({ text: z.string().max(2000) }),
741
+ access: { roles: ['guest', 'admin'] },
742
+ async execute({ db, record, input }) {
743
+ // The route loaded `record` through its firewall, then verified guestOf
744
+ // against record.eventId. Only domain logic remains here.
745
+ return db.insert(comments).values({
746
+ sessionId: record.id,
747
+ text: input.text,
748
+ });
741
749
  },
742
- }
743
-
744
- // features/sessions/sessions.ts — firewall scopes rows; action gates on BA role
745
- firewall: [
746
- { field: 'organizationId', equals: 'ctx.activeOrgId' },
747
- { field: 'eventId', via: 'guestOf' }, // ← row-level relationship check
748
- ],
749
- actions: {
750
- comment: defineAction({
751
- access: { roles: ['member', 'admin'] }, // ← BA role only on the action
752
- input: z.object({ text: z.string() }),
753
- execute: async (input, ctx, db, record) => {
754
- // record is already filtered by the firewall — guest membership
755
- // is enforced before this handler runs.
756
- return db.insert(comments).values({ ... });
757
- },
758
- }),
759
- }
750
+ });
760
751
  ```
761
752
 
762
- This pattern composes cleanly: the firewall guarantees the caller has the relationship to the record being acted on; the action's access list keeps the role surface obvious.
753
+ Simple role arms are checked before the record lookup to preserve ID-probe
754
+ resistance. Relationship arms run only after the record has been loaded through
755
+ the firewall, because the record supplies the relationship key. No manual
756
+ lookup or firewall exception is required.
763
757
 
764
- See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture, including `loads` / `exposeAs` and the `firewall: { exception: true }` escape hatch.
758
+ See [Access — relationship
759
+ authorization](/compiler/definitions/access#relationship-based-authorization)
760
+ for the full surface matrix, namespace hoisting, and tenant-context stamping.
765
761
 
766
762
  ## Scoped Database
767
763
 
@@ -870,11 +866,12 @@ export default defineTable(attendanceEvidence, {
870
866
  });
871
867
  ```
872
868
 
873
- `databaseAccess` supports `select`, `insert`, `update`, and `delete`. Its rule
874
- language is intentionally smaller than application access: `principals`,
875
- `roles`, recursive `or`/`and`, and record `equals` against a DB-visible account
876
- or principal context value. `userRole`, functions, request/body values, and
877
- other predicate operators are compile errors.
869
+ `databaseAccess` supports `select`, `insert`, `update`, and `delete` with a
870
+ purpose-built, SQL-pushable rule language: `principals`, `roles`, recursive
871
+ `or`/`and`, and record `equals` against a DB-visible account or principal
872
+ context value. Application-only values such as `userRole`, functions, and
873
+ request/body fields stay at the action access layer; the compiler refuses them
874
+ inside database RLS rather than pretending PostgreSQL can evaluate them.
878
875
 
879
876
  Every authorization path must contain at least one nonempty record equality.
880
877
  A principal-only or role-only leaf is rejected; every `or` arm must be bounded.
@@ -895,13 +892,14 @@ surface, while `SYSADMIN` retains its explicit `cms.sysadmin` prerequisite. The
895
892
  feature is rejected outside Cloudflare + Neon Hyperdrive because those targets
896
893
  cannot guarantee request-scoped Postgres claims.
897
894
 
898
- ### Relational queries are blocked (fail-closed)
895
+ ### Scoped relational-query safety
899
896
 
900
897
  Drizzle's relational query API — `db.query.<table>.findFirst()` /
901
898
  `findMany()` (including nested `with:` relations) — builds its SQL from the
902
899
  relations config and your `where` alone, so the scoped wrapper cannot inject
903
- the org/owner/team firewall into it. Rather than silently returning rows from
904
- every tenant, the scoped `db` **throws** on any `db.query.<table>` access:
900
+ the org/owner/team firewall into it. The scoped `db` therefore exposes the
901
+ Drizzle select builder—the path where Quickback can guarantee firewall
902
+ injection—and refuses `db.query.<table>` rather than returning unscoped rows:
905
903
 
906
904
  ```typescript
907
905
  async execute({ db, input }) {
@@ -913,10 +911,11 @@ async execute({ db, input }) {
913
911
  }
914
912
  ```
915
913
 
916
- If you genuinely need the relational API, declare the action `unsafe: true`
917
- and query `unsafeDb.query` with an **explicit** scope predicate in the WHERE
918
- (e.g. `eq(media.organizationId, ctx.activeOrgId)`), exactly like any other
919
- unsafe read.
914
+ For nested reads, compose joins with the scoped select builder. If a
915
+ Postgres-specific relational query is genuinely required, make the boundary
916
+ explicit with `unsafe: true` and query `unsafeDb.query` with the full scope
917
+ predicate in the `WHERE` (for example,
918
+ `eq(media.organizationId, ctx.activeOrgId)`).
920
919
 
921
920
  ### Unsafe Mode
922
921
 
@@ -967,9 +966,11 @@ handle (`createServiceDb`). That handle sets the `quickback.service_role`
967
966
  transaction marker instead of caller claims, and generated RLS grants it an
968
967
  explicit per-table bypass policy. The sysadmin guard and mandatory audit log
969
968
  therefore protect the same boundary that receives the RLS bypass. The
970
- audit-logging contract is otherwise identical to D1. Neon with
971
- `connectionMode: 'websocket'` does not support unsafe actions yet and fails
972
- the compile with a descriptive error.
969
+ audit-logging contract is otherwise identical to D1. On Cloudflare, both HTTP
970
+ and Hyperdrive are supported. Hyperdrive is the recommended lane when an unsafe
971
+ action also needs an interactive transaction. The deprecated Node/Bun WebSocket
972
+ mode is refused for unsafe actions because it cannot provide the same
973
+ request-scoped service-role boundary.
973
974
 
974
975
  `PUBLIC` actions also receive mandatory audit logging (same audit table), since unauthenticated endpoints are high-risk by nature.
975
976
 
@@ -120,6 +120,18 @@ have. No subpath.
120
120
  | Header | Behavior |
121
121
  |---|---|
122
122
  | `If-Match` | Optimistic concurrency against the **root revision** — the root's `updatedAt` (or the injected `modifiedAt` audit column). Accepted value forms: `W/"<revision>"`, `"<revision>"`, or the bare revision value, where `<revision>` is the raw value of the revision column as returned in the root row. **Do not echo `GET /:id`'s `ETag` header into `If-Match`** — that ETag is the contract layer's body-hash ETag, not this revision, and will always **412**. Compared inside the transaction; mismatch → **412**. Every accepted changeset touches the revision. A root with no revision column answers `If-Match` with **428 PRECONDITION_UNSUPPORTED** — never silently ignored; the POST variant always answers 428 (no pre-existing revision to match). |
123
+
124
+ `If-Match` is honored with the **identical comparator on the plain
125
+ `application/json` write lanes** too: single-record `PATCH`, `PUT`, and
126
+ `DELETE` compare the supplied revision against the fetched row (mismatch →
127
+ **412**), and `PATCH`/`PUT` additionally pin the revision into the write's
128
+ `WHERE` (compare-and-swap), so a concurrent writer between the fetch and the
129
+ write surfaces as **412** on every provider — including the transaction-less
130
+ D1 / Neon-HTTP lanes. A `PUT` with `If-Match` against a missing row is a
131
+ **412** (RFC 9110: no current representation), never a silent create. Tables
132
+ with no revision column, and every **batch** endpoint (`If-Match` is a
133
+ single-resource precondition), answer **428 PRECONDITION_UNSUPPORTED**. A
134
+ supplied precondition is **never silently ignored** anywhere.
123
135
  | `Idempotency-Key` | The standard write-retry key. Claims are principal-scoped — a replayed key from a different principal is a 422, never a cached-body leak. |
124
136
  | `Prefer` | `return=representation` (default) or `return=minimal`. |
125
137
 
@@ -326,11 +338,65 @@ the success path, so **no frames emit** for the partially-applied prefix —
326
338
  no-tx changeset **does** emit, still with `transactional: false`. Never assume
327
339
  "row written ⇒ event fired"; `meta.transactional` is the contract.
328
340
 
329
- > **Deferred out of v1:** embedding reindex on the changeset lane, `notify`
330
- > (device push — a WS broadcast is not an APNs/web-push delivery), and lifting
331
- > `afterCommit` onto plain tables/actions. The compiler still **warns** when an
332
- > `owns` root/child declares `realtime` **without** `afterCommit`, or declares
333
- > `embeddings`, so a silent asymmetry can't be enabled unknowingly.
341
+ ### `reindex` — re-embed the committed root
342
+
343
+ ```ts
344
+ afterCommit: {
345
+ reindex: true, // requires the root's `embeddings` block
346
+ }
347
+ ```
348
+
349
+ `reindex: true` re-enqueues the **committed root row** for embedding
350
+ regeneration on the same at-least-once `EMBEDDINGS_QUEUE` lane the plain and
351
+ batch routes use — enqueued only **after** the changeset commits, so a
352
+ rolled-back changeset produces no orphan embedding jobs. Fail-closed rules:
353
+
354
+ - The root **must** declare an `embeddings` block — `reindex: true` without
355
+ one is a compile error (there is nothing to re-embed).
356
+ - `embeddings.onInsert` / `onUpdate: false` gate create/update changesets
357
+ exactly like the plain routes; a field-watch `onUpdate: [...]` array is
358
+ treated as **always** (changeset ops are aggregate-level, not a field diff).
359
+ - Reindex covers the **root row only**. Owned children with `embeddings` still
360
+ warn at compile time — keep child writes on the plain routes, or enqueue
361
+ from an authored action.
362
+
363
+ ### `notify` — device push after commit
364
+
365
+ ```ts
366
+ afterCommit: {
367
+ notify: {
368
+ bookingChanged: {
369
+ delivery: "thisEvent", // defineRealtimeDelivery — the audience
370
+ title: "Booking updated",
371
+ body: "Reservation {reservationId} changed",
372
+ tag: "res-{reservationId}", // collapse key (templated)
373
+ payload: { eventId: "root.eventId", reservationId: "rootId" },
374
+ },
375
+ },
376
+ }
377
+ ```
378
+
379
+ Requires `push: { provider: 'web-push' }` — declaring `notify` without the
380
+ provider is a compile error. The audience is a **delivery profile**, resolved
381
+ with the same fail-closed lookup and the **same disclosure gates** as
382
+ `broadcast` (masked columns, `q.stamp` proven identity, child-id enumeration
383
+ — the gates are shared code, not a parallel set). `{key}` template
384
+ placeholders must be mapped `payload` keys; an unresolvable placeholder is a
385
+ compile error, and a null placeholder value at runtime skips the push
386
+ (fail-closed — nobody gets a blank notification).
387
+
388
+ Fan-out: a scope-keyed delivery targets subscriptions tagged
389
+ `scope:<room key>`; an `organizationId` + `userIdFrom` delivery targets that
390
+ user's devices; profile roles AND-compose as a `role:` tag filter. Delivery
391
+ rides the `PUSH_FANOUT_QUEUE` after commit — at-least-once, best-effort,
392
+ never rolling back the changeset. A delivery that resolves to no audience
393
+ pushes to nobody, mirroring the ws broadcast lane exactly.
394
+
395
+ > **Deferred out of v1 (still):** lifting `afterCommit` onto plain
396
+ > tables/actions. The compiler still **warns** when an `owns` root/child
397
+ > declares `realtime` **without** `afterCommit`, or when an owned **child**
398
+ > declares `embeddings` (root embeddings are covered by `reindex`), so a
399
+ > silent asymmetry can't be enabled unknowingly.
334
400
 
335
401
  ## Atomicity — honest, per provider
336
402
 
@@ -387,5 +453,6 @@ rendering only).
387
453
 
388
454
  Full-document `replace` diff sugar (and its `key:` reconciliation field), the
389
455
  `application/json-patch+json` representation, cross-branch `$lid` references,
390
- nested `Prefer: return=representation`, `?include=` aggregate reads, and
391
- find-or-create roots by business key (`conflictTarget`).
456
+ nested `Prefer: return=representation`, and find-or-create roots by business
457
+ key (`conflictTarget`). `?include=<ownsRelation>` aggregate reads have
458
+ **landed** — see [read → Aggregate Reads](/compiler/definitions/read#aggregate-reads).
@@ -47,6 +47,6 @@ Quick reference for terms used across the Quickback documentation.
47
47
 
48
48
  | Term | Definition |
49
49
  |------|-----------|
50
- | **Cloud Compiler** | The remote compilation service at `compiler.quickback.dev`. The CLI sends your definitions and receives generated code back. |
50
+ | **Compiler** | The generator behind `quickback compile`. Use the zero-setup hosted service at `compiler.quickback.dev`, or run the same compiler image locally when source policy or build availability calls for it. |
51
51
  | **Stack** | The runtime infrastructure (Cloudflare Workers, D1, KV, R2, Better Auth) where your compiled API runs. |
52
52
  | **Template** | A pre-configured project starter (`cloudflare`, `bun`, `turso`) created by `quickback create`. |