@quickback-dev/cli 0.66.5 → 0.66.6

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 (77) hide show
  1. package/README.md +0 -1
  2. package/dist/index.js +1 -1
  3. package/dist/skill/SKILL.md +0 -2
  4. package/dist/skill/docs/api/openapi.md +1 -1
  5. package/dist/skill/docs/configure/auth.md +4 -5
  6. package/dist/skill/docs/configure/domains.md +1 -1
  7. package/dist/skill/docs/configure/index.md +4 -4
  8. package/dist/skill/docs/configure/security.md +3 -3
  9. package/dist/skill/docs/define/access.md +23 -3
  10. package/dist/skill/docs/define/actions/defining.md +2 -2
  11. package/dist/skill/docs/define/actions/record-and-standalone.md +1 -2
  12. package/dist/skill/docs/define/areas.md +14 -15
  13. package/dist/skill/docs/define/changesets.md +5 -0
  14. package/dist/skill/docs/define/diagnostics.md +2 -2
  15. package/dist/skill/docs/define/fga.md +1 -1
  16. package/dist/skill/docs/define/firewall.md +5 -5
  17. package/dist/skill/docs/define/guards.md +2 -1
  18. package/dist/skill/docs/define/masking.md +2 -2
  19. package/dist/skill/docs/define/relationships.md +8 -10
  20. package/dist/skill/docs/define/scopes.md +1 -1
  21. package/dist/skill/docs/index.md +0 -6
  22. package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -2
  23. package/dist/skill/docs/platform/realtime/durable-objects.md +1 -1
  24. package/dist/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
  25. package/dist/skill/docs/platform/webhooks/inbound.md +1 -1
  26. package/dist/skill/docs/tooling/claude-skill.md +0 -7
  27. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +1 -1
  28. package/dist/skill/docs/tooling/output.md +7 -6
  29. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  30. package/dist/skill/docs/ui/account/features/organizations.md +1 -1
  31. package/dist/skill/docs/ui/admin/index.md +1 -1
  32. package/dist/skill/docs/ui/admin/owned-records.md +81 -0
  33. package/dist/skill/docs/ui/admin/schema-format.md +16 -0
  34. package/package.json +1 -1
  35. package/src/skill/SKILL.md +0 -2
  36. package/src/skill/docs/api/openapi.md +1 -1
  37. package/src/skill/docs/configure/auth.md +4 -5
  38. package/src/skill/docs/configure/domains.md +1 -1
  39. package/src/skill/docs/configure/index.md +4 -4
  40. package/src/skill/docs/configure/security.md +3 -3
  41. package/src/skill/docs/define/access.md +23 -3
  42. package/src/skill/docs/define/actions/defining.md +2 -2
  43. package/src/skill/docs/define/actions/record-and-standalone.md +1 -2
  44. package/src/skill/docs/define/areas.md +14 -15
  45. package/src/skill/docs/define/changesets.md +5 -0
  46. package/src/skill/docs/define/diagnostics.md +2 -2
  47. package/src/skill/docs/define/fga.md +1 -1
  48. package/src/skill/docs/define/firewall.md +5 -5
  49. package/src/skill/docs/define/guards.md +2 -1
  50. package/src/skill/docs/define/masking.md +2 -2
  51. package/src/skill/docs/define/relationships.md +8 -10
  52. package/src/skill/docs/define/scopes.md +1 -1
  53. package/src/skill/docs/index.md +0 -6
  54. package/src/skill/docs/platform/auth/jwt-optimization.md +2 -2
  55. package/src/skill/docs/platform/realtime/durable-objects.md +1 -1
  56. package/src/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
  57. package/src/skill/docs/platform/webhooks/inbound.md +1 -1
  58. package/src/skill/docs/tooling/claude-skill.md +0 -7
  59. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +1 -1
  60. package/src/skill/docs/tooling/output.md +7 -6
  61. package/src/skill/docs/ui/account/features/admin.md +1 -1
  62. package/src/skill/docs/ui/account/features/organizations.md +1 -1
  63. package/src/skill/docs/ui/admin/index.md +1 -1
  64. package/src/skill/docs/ui/admin/owned-records.md +81 -0
  65. package/src/skill/docs/ui/admin/schema-format.md +16 -0
  66. package/dist/skill/docs/changelog/index.md +0 -945
  67. package/dist/skill/docs/changelog/v0.1x.md +0 -1202
  68. package/dist/skill/docs/changelog/v0.2x.md +0 -589
  69. package/dist/skill/docs/changelog/v0.3x.md +0 -1152
  70. package/dist/skill/docs/changelog/v0.4x.md +0 -1108
  71. package/dist/skill/docs/changelog/v0.5x.md +0 -885
  72. package/src/skill/docs/changelog/index.md +0 -945
  73. package/src/skill/docs/changelog/v0.1x.md +0 -1202
  74. package/src/skill/docs/changelog/v0.2x.md +0 -589
  75. package/src/skill/docs/changelog/v0.3x.md +0 -1152
  76. package/src/skill/docs/changelog/v0.4x.md +0 -1108
  77. package/src/skill/docs/changelog/v0.5x.md +0 -885
@@ -119,7 +119,7 @@ The auto-mounted middleware is **secure by default** — anonymous WebSocket upg
119
119
 
120
120
  The default gate only checks **whether** the caller is authenticated, not whether they're allowed in *this* room. For per-room authorization, the `access` field on the binding lets the compiler emit a path-scoped gate that runs your existing resource firewall + `read.access` pipeline before the WebSocket upgrade — no hand-written code, same status semantics as `GET /api/v1/<resource>/:id`.
121
121
 
122
- ### Per-room authorization via `access` (v0.12+)
122
+ ### Per-room authorization via `access`
123
123
 
124
124
  ```ts
125
125
  // quickback/quickback.config.ts
@@ -149,13 +149,13 @@ bindings: {
149
149
  },
150
150
 
151
151
  // Multi-table feature: pin the gate to a specific table so the
152
- // firewall + id query is unambiguous (v0.16.1+).
152
+ // firewall + id query is unambiguous.
153
153
  {
154
154
  name: 'NotepadInteractions', className: 'NotepadInteractions', from: 'lib/NotepadInteractions',
155
155
  access: { resource: { feature: 'interactions', table: 'interactions' } },
156
156
  },
157
157
 
158
- // Room keyed by a unique non-PK column (v0.36+). A Yjs page editor is
158
+ // Room keyed by a unique non-PK column. A Yjs page editor is
159
159
  // addressed by `event_pages.yjsRoomId`, not the row id — `key` tells the
160
160
  // gate which column the roomId matches.
161
161
  {
@@ -188,7 +188,7 @@ What the compiler emits:
188
188
  - **Multi-resource form** — same gate but with a regex parser dispatching to per-kind firewall lookups. Unknown kinds 400 at the gate. Each `resources[kind].resource` accepts either form (string shorthand or `{ feature, table, key? }`).
189
189
  - **`access: { roomIdEquals: 'ctx.userId' }`** — an **identity gate** for rooms with no backing table, where the roomId *is* the caller's own id. Emits `app.use('/realtime/<kebab>/*', …)` that 401s anonymous, 400s a missing segment, and 403s unless the decoded room segment equals `ctx.userId`. No schema import, no firewall, no DB query — a string compare against the server-resolved `ctx`. Use `'ctx.activeOrgId'` for a per-org room. This is the right gate for per-user gateways, presence, or inbox DOs keyed on `ns.idFromName(ctx.userId)`. Only `'ctx.userId'` and `'ctx.activeOrgId'` are accepted (validated at compile time); anything else is a build error. Distinct from `resource` because there's no row to firewall — it closes the cross-user hole that "no `access` declared" leaves open (any authenticated user could otherwise open another user's room via the catchall).
190
190
  - **`access: 'public'`** — `app.use('/realtime/<kebab>/*', …)` that just passes through. Use for anonymous game lobbies / public collab pads where the room itself is the unit of access.
191
- - **No `access` declared** — falls through to the catchall `/realtime/*` gate that just checks `ctx.authenticated`. (v0.11.1 behavior.)
191
+ - **No `access` declared** — falls through to the catchall `/realtime/*` gate that just checks `ctx.authenticated`.
192
192
 
193
193
  Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade. The string shorthand requires the feature to have exactly one resourceful table; multi-table features must use the long form `{ feature, table }` to pin a specific table. When `key` is set, the column is checked against the pinned table's schema.
194
194
 
@@ -178,7 +178,7 @@ Events without an `externalId` (NULL) are not deduplicated. SQLite treats NULLs
178
178
 
179
179
  ### Migrating an existing deployment
180
180
 
181
- The unique index was added in v0.10.x. Existing deployments may have duplicate rows from before the constraint existed; drizzle-kit's migration will fail until they are cleaned up. Run this once before applying the migration:
181
+ If an existing deployment contains duplicate rows, drizzle-kit's unique-index migration will fail until they are cleaned up. Run this once before applying the migration:
182
182
 
183
183
  ```sql
184
184
  DELETE FROM webhook_events
@@ -303,10 +303,3 @@ The MCP server always uses the latest installed version automatically.
303
303
  - [Getting Started](/start/quickstart) - Get your first Quickback project running
304
304
  - [Definitions Overview](/define) - Understand the security layer model
305
305
  - [npm package](https://www.npmjs.com/package/@quickback-dev/cli) - CLI package
306
-
307
- ## Feedback
308
-
309
- Found an issue with the AI tools integration?
310
-
311
- - [GitHub Issues](https://github.com/kardoe/quickback/issues)
312
- - [Quickback Documentation](https://docs.quickback.dev)
@@ -94,7 +94,7 @@ The server echoes the chosen version back as the response `X-Quickback-Stream` h
94
94
 
95
95
  Multi-megabyte SPA bundles (CMS + Account, with sourcemaps) take long enough to `JSON.stringify` that the v1 single-frame `result` event blocks Cloudflare's container event loop. Two things break: Docker's `HEALTHCHECK` fails, and the CLI's 120-second connection timeout fires before the body flushes. v2 emits files one at a time and yields back to the event loop every 10 files (`setImmediate`), keeping `/health` responsive and TCP backpressure alive.
96
96
 
97
- The `@quickback-dev/cli` v0.10.x and later send `X-Quickback-Stream: v2` automatically. v1 is preserved for older clients.
97
+ The `@quickback-dev/cli` sends `X-Quickback-Stream: v2` automatically.
98
98
 
99
99
  ### Event shapes (v2)
100
100
 
@@ -151,9 +151,9 @@ The compiler's output is a manifest of files to **write**. It has no way to say
151
151
 
152
152
  For most moves that gap is invisible: the CLI wipes `src/` from the manifest
153
153
  before each write, so relocating a file *within* `src/` cleans up after itself.
154
- It bites the moment a path crosses that boundary — v0.60 moved the spec blobs
155
- from the project root into `src/apps/__quickback/spec/`, and the root copies
156
- survived every later compile as multi-MB orphans that tooling kept reading.
154
+ It bites the moment a path crosses that boundary. For example, spec blobs now
155
+ live in `src/apps/__quickback/spec/`; retired root copies can survive as
156
+ multi-MB orphans that tooling keeps reading.
157
157
 
158
158
  So the compiler now also returns **retired paths** — things it used to emit and
159
159
  no longer does — and the CLI deletes them:
@@ -172,9 +172,8 @@ unrecoverable while a missed one is only untidy:
172
172
  actually in this compile's manifest. Disable the surface
173
173
  (`openapi.generate: false`) and neither path is emitted, so nothing is
174
174
  removed.
175
- - A path the current manifest still writes is **never** deleted — that is what
176
- keeps an older compiler, which still writes to the old location, from having
177
- its live output pulled out from under it.
175
+ - A path the current manifest still writes is **never** deleted, so live output
176
+ cannot be pulled out from under the compile.
178
177
  - The CLI re-checks both conditions itself and refuses any path that would
179
178
  escape the output directory.
180
179
 
@@ -342,6 +341,8 @@ reports/
342
341
  The signature file uses HMAC-SHA256 when a signing key is configured, otherwise it falls back to SHA-256 digest mode.
343
342
  Set `compiler.securityContracts.report.signature.required: true` to fail compilation when a signing key is missing.
344
343
 
344
+ The report names the compiler that produced it twice: `compilerVersion` is the semver, and `compilerBuildId` is `<version>@<gitSha>@<builtAt>` — the same string the compiler's `/health` endpoint reports as `buildId`. The semver is a floor that can serve several hosted builds, so a drift tripwire should pin on `compilerBuildId`, not `compilerVersion`.
345
+
345
346
  ### Realtime
346
347
 
347
348
  When any feature has `realtime` configured:
@@ -45,7 +45,7 @@ These run on `/auth/v1/admin/*`, emitted by Quickback because Better Auth's orga
45
45
 
46
46
  The admin panel is restricted to platform roles on the Better Auth user record: **`appmanager`** (the control plane) and **`sysadmin`** (which adds cross-tenant data access on top). Everyone else is redirected away from `/admin`.
47
47
 
48
- > **`role: "admin"` is not a platform role.** By default the compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]`, so a user set to `"admin"` passed the UI guard and then got `403` from every admin API call — an operator who looked promoted and could not act. Removed in v0.62; migrate those rows to `"appmanager"`.
48
+ > **`role: "admin"` is not a platform role.** By default the compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]`. Migrate rows with `role: "admin"` to `"appmanager"`.
49
49
  >
50
50
  > A project that declares `plugins: { admin: { adminRoles, roles } }` gets **exactly** that: the declared `adminRoles` list and role → access-controller map are emitted verbatim (`appmanager: userAc` narrows the provisioning operator to no admin API at all; `adminRoles: ["sysadmin"]` keeps set-role / impersonate / ban for `sysadmin` only). The compiler never re-widens a declared role, and refuses a declaration it cannot honour.
51
51
 
@@ -16,7 +16,7 @@ Account UI provides a complete organization management interface when `VITE_ENAB
16
16
  - Change roles and remove members — actions are filtered per-target by the role hierarchy (non-owners can't manage owner-role members)
17
17
  - Leave the organization
18
18
 
19
- > **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/define/access) rules — with [`auth.roleHierarchy`](/define/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above." [Custom org roles](/define/access#custom-org-roles) declared in your access trees are auto-registered with the organization plugin (v0.46+), so `invite-member` / `update-member-role` accept them too.
19
+ > **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/define/access) rules — with [`auth.roleHierarchy`](/define/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above." [Custom org roles](/define/access#custom-org-roles) declared in your access trees are auto-registered with the organization plugin, so `invite-member` / `update-member-role` accept them too.
20
20
 
21
21
  ## Invitations
22
22
 
@@ -207,7 +207,7 @@ The gates that carry real data:
207
207
 
208
208
  Your resource API endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
209
209
 
210
- > **Breaking in v0.62.** `cms.access` was renamed from `"admin" | "user"`, and both old values meant something different: `"admin"` admitted `appmanager`, and `"user"` admitted *any* authenticated caller — including one belonging to no organization, who then reached a CMS with nothing in it. The old spellings are rejected at compile time rather than aliased, because aliasing would preserve the old behaviour under a familiar name. Migrate `"admin"` → `"sysadmin"`, `"user"` → `"member"`.
210
+ > `cms.access` accepts `"sysadmin"` or `"member"`. The retired `"admin"` and `"user"` spellings are rejected at compile time; migrate `"admin"` → `"sysadmin"` and `"user"` → `"member"`.
211
211
 
212
212
 
213
213
  #### What a blocked caller actually sees
@@ -0,0 +1,81 @@
1
+ # Owned Records
2
+
3
+ A table that declares an [`owns` boundary](/define/changesets) gets its owned
4
+ children rendered **inline on the record page**: each relation appears as a
5
+ section below the record's fields, with a row table and Add / Edit / Delete
6
+ controls. Line items live on the expense report, not in a sidebar collection.
7
+
8
+ ## When a relation renders
9
+
10
+ All three must hold — a relation missing any of them is skipped:
11
+
12
+ 1. The relation is declared in the root's `owns`.
13
+ 2. The relation name is in the root's `read.include` allowlist — reads ride
14
+ `GET /:id?include=<relation>`, and a non-allowlisted include is a 400.
15
+ 3. The child table exists in the schema registry.
16
+
17
+ {/* doc-compile: skip — the fence is the owns + include wiring only; columns, firewall, guards, and the child table are elided. */}
18
+ ```ts title="quickback/features/expenseReports/expenseReports.ts"
19
+ export default feature("expenseReports", {
20
+ // ...columns, firewall, guards, crud...
21
+ owns: {
22
+ lineItems: { table: "lineItems", fk: "reportId", inherit: ["organizationId"] },
23
+ },
24
+ read: {
25
+ access: { roles: ["member+"] },
26
+ include: ["lineItems"], // without this, the CMS has no way to read the rows
27
+ },
28
+ });
29
+ ```
30
+
31
+ ## Writes go through the changeset engine
32
+
33
+ Every Add, Edit, and Delete is a single-op
34
+ [changeset](/define/changesets) `PATCH` on the **root** —
35
+ `Content-Type: application/vnd.quickback.changeset+json` — never a raw child
36
+ route. The generated aggregate engine enforces the child's own access,
37
+ guards, body schema, and firewall on every op, and stamps the spine FK and
38
+ `inherit` columns from the firewall-verified parent row.
39
+
40
+ Consequences in the UI:
41
+
42
+ - The child's `fk` and `inherit` columns are **excluded from the form** — the
43
+ engine stamps them, and a client-supplied value is rejected.
44
+ - The Add / Edit / Delete buttons gate on the **child table's** `create` /
45
+ `update` / `delete` access for the signed-in role, exactly like the child's
46
+ own raw routes would.
47
+ - Child deletes are soft (changeset v1 admits soft-delete children only).
48
+
49
+ ## `routes: false` children
50
+
51
+ The usual shape for a pure composition child — line items that only ever
52
+ exist inside a report — is `routes: false` on every op plus
53
+ `cms: { internal: true }`:
54
+
55
+ {/* doc-compile: skip — crud-op fragments without the surrounding table definition. */}
56
+ ```ts title="quickback/features/expenseReports/lineItems.ts"
57
+ read: { access: { roles: ["member+"] }, routes: false },
58
+ create: { access: { roles: ["member+"] }, routes: false },
59
+ update: { access: { roles: ["member+"] }, routes: false },
60
+ delete: { access: { roles: ["member+"] }, routes: false, mode: "soft" },
61
+
62
+ cms: { internal: true }, // no standalone sidebar entry
63
+ ```
64
+
65
+ `routes: false` keeps the access declared (it is the changeset admission
66
+ gate) but mounts no raw HTTP route. The CMS reads the registry's
67
+ `routesDisabled` list and suppresses every raw-CRUD affordance for those ops
68
+ — New button, row Edit/Delete, record-page Edit/Delete, and inline cell
69
+ editing — so it never renders a button whose request can only 405. The
70
+ owned-records section is unaffected: its writes are changeset ops, which
71
+ `routes: false` deliberately leaves open.
72
+
73
+ Note the child's `read` access above is what gates the embedded rows:
74
+ `?include=` inherits the **target's** read access, firewall, and masking. A
75
+ child readable only by `admin+` renders an empty section for members.
76
+
77
+ ## Next Steps
78
+
79
+ - **[Changesets](/define/changesets)** — the `owns` boundary and the wire contract
80
+ - **[Record Layouts](/ui/admin/record-layouts)** — grouping the root's own fields
81
+ - **[Schema Format](/ui/admin/schema-format)** — `ownsRelations`, `readInclude`, `routesDisabled`
@@ -62,6 +62,18 @@ interface TableMeta {
62
62
  inputHints?: Record<string, string>;
63
63
  layouts?: Record<string, CmsLayout>;
64
64
  internal?: boolean;
65
+ ownsRelations?: Record<string, OwnsRelation>;
66
+ ownedBy?: string;
67
+ readInclude?: string[];
68
+ routesDisabled?: string[];
69
+ }
70
+
71
+ interface OwnsRelation {
72
+ table: string; // owned child table (camelCase registry name)
73
+ fk: string; // FK on the child pointing at this root — compiler-stamped
74
+ inherit?: string[]; // parent columns copied onto inserted children — compiler-stamped
75
+ refs?: Record<string, string>; // client-supplied pointers at independent entities
76
+ owns?: Record<string, OwnsRelation>; // nested owned relations
65
77
  }
66
78
  ```
67
79
 
@@ -86,6 +98,10 @@ interface TableMeta {
86
98
  | `inputHints` | Map of column name to preferred CMS input type (e.g., `"richtext"`, `"select"`, `"textarea"`, `"checkbox"`) |
87
99
  | `layouts` | Named record page layouts keyed by layout name (see CmsLayout below) |
88
100
  | `internal` | When `true`, table is hidden from CMS sidebar |
101
+ | `ownsRelations` | The [`owns`](/define/changesets) config verbatim — the CMS renders these as inline [owned-records sections](/ui/admin/owned-records) on the root's record page |
102
+ | `ownedBy` | Set on owned children: the aggregate-root table that owns this table |
103
+ | `readInclude` | The `read.include` allowlist — tokens fetchable via `?include=` |
104
+ | `routesDisabled` | Ops declared `routes: false` — access exists (changeset admission) but no raw HTTP route, so the CMS suppresses New/Edit/Delete buttons and inline editing for them |
89
105
 
90
106
  ## ColumnMeta
91
107
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.66.5",
3
+ "version": "0.66.6",
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",
@@ -443,6 +443,4 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
443
443
  - `claude-skill` / `claude-code` — this skill
444
444
  - `cloud-compiler/{index,authentication,endpoints,local-compiler,troubleshooting}` — the hosted build service
445
445
 
446
- **Other** — `docs/changelog/index.md`
447
-
448
446
  For online navigation: <https://docs.quickback.dev>.
@@ -232,7 +232,7 @@ Or enable the in-project browser via the [`docs` config option](#interactive-api
232
232
 
233
233
  Alongside the spec, every compile writes `reports/operations.manifest.json` — a
234
234
  stable, machine-readable index of the full route surface (resource, action,
235
- view, and auth routes; since v0.47 also the realtime, storage, and FGA
235
+ view, auth, realtime, storage, and FGA routes, plus
236
236
  surfaces):
237
237
 
238
238
  ```json
@@ -55,7 +55,7 @@ The short version, before the knob-by-knob detail:
55
55
  - **Default: 180-second TTL, auto-refreshed.** Every authenticated call returns a fresh token via the `set-auth-token` header, so the low TTL is invisible to logged-in users. The worst-case window for a stolen or pre-revocation token is 3 minutes — and you can shrink it to 30 seconds with one config line.
56
56
  - **Need revocation faster than the TTL?** Set [`revocationCheck: 'kv'`](#revocationcheck-none--kv--token-revocation-strategy). Revoked tokens are rejected within seconds; revocation stamps are written automatically on sign-out and session revocation (per session), on password change with `revokeOtherSessions`, account deletion, user ban, org-member removal, role change, and changes to scope-conferring relationship rows. Long-lived tokens are therefore safe to pair with it: a remote "sign out everywhere" kills a lost device's bearer.
57
57
 
58
- Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session) and propagates cross-PoP in ~60s. It **fails closed** — if KV can't be read, the bearer isn't trusted and a bearer-only caller gets a retryable `503`, so enabling it ties bearer availability to KV. If you need per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling — and [tell us about your use case](https://github.com/kardoe/quickback/issues); an opaque-session mode is under consideration.
58
+ Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session) and propagates cross-PoP in ~60s. It **fails closed** — if KV can't be read, the bearer isn't trusted and a bearer-only caller gets a retryable `503`, so enabling it ties bearer availability to KV. If you need per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling.
59
59
 
60
60
  ### Behavior recap
61
61
 
@@ -130,7 +130,7 @@ Default `'none'`.
130
130
  | `'none'` | No revocation check. Stolen / pre-revocation tokens valid until TTL expires (scope claims: until the carry-forward cap). Use a low `expiresIn` to bound the replay window. | 0 |
131
131
  | `'kv'` | Fast-path checks per-principal revocation timestamps in the project's existing `KV` binding before trusting a verified token. Fails closed: an unreadable store means the bearer is not trusted. | 2+ KV reads (~5-15ms, edge-cached) |
132
132
 
133
- `'kv'` (v0.45+, **Cloudflare runtime only**) keeps the fast-path stateless against the auth DB (still 0 D1 queries). There is nothing extra to provision — entries ride the `KV` binding every project already has, prefixed `qbrev:` and self-expiring after the maximum token lifetime, so the store never accumulates.
133
+ `'kv'` (**Cloudflare runtime only**) keeps the fast-path stateless against the auth DB (still 0 D1 queries). There is nothing extra to provision — entries ride the `KV` binding every project already has, prefixed `qbrev:` and self-expiring after the maximum token lifetime, so the store never accumulates.
134
134
 
135
135
  A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's proof time) is **at or before** the stored timestamp for any principal key it rides on:
136
136
 
@@ -147,8 +147,7 @@ Semantics worth knowing:
147
147
 
148
148
  - **Revoke-on-touch for scopes:** any update or delete of a conferring row stamps the revocation, without evaluating whether the change actually ended the relationship. A false positive just forces a cheap re-prove (`/scope/v1/enter` or a minting namespace route).
149
149
  - **Scope proof time is per kind:** a token can carry several scope kinds proven at different instants, so each entry carries its own proof stamp (`sctMs`, `m<ms>`) and is compared against its own marker. Proving one kind never restamps the others — re-entering `event` cannot bring a revoked `location` claim back to life. Entries minted before the release that added the stamp carry none, and fall back to the token-level `sct`/`sctMs` until they expire (bounded by the carry-forward cap plus one TTL).
150
- - **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format version, not a magnitude the reader guesses at) and tokens carry millisecond companions (`iatMs` / `sctMs`) alongside the standards-compatible seconds claims, so a token minted a few milliseconds before the revocation is rejected — while one legitimately re-minted *after* it in that same second is still accepted. Tokens and markers written by v0.60.4 or earlier are handled **conservatively**: with no sub-second information on one side, the whole marker second is revoked. That over-revocation is bounded — the last old token expires within its TTL, and the last old marker within the entry lifetime. Like any rejected token it costs the caller a `401`, not a silent recovery: the bearer falls through unauthenticated (its cookie having been stripped, per the next bullet), and the client re-authenticates for a fresh token.
151
- - **Do not straddle the v0.61.0 upgrade.** A worker from **before** v0.61.0 reads `m<ms>` markers as `NaN` and treats them as *no revocation at all* — not as a corrupt entry. So rolling back across this release, or pointing two differently-versioned deploy targets at one shared KV namespace, means every revocation written by the new version is **silently unenforced** by the old one until the entry expires (`ENTRY_TTL_SECONDS`, ~19 minutes at default settings). Upgrade all targets sharing a namespace together; if you must roll back, treat outstanding bearer tokens as unrevoked for that window — lower `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
150
+ - **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format marker, not a magnitude the reader guesses at) and tokens carry millisecond companions (`iatMs` / `sctMs`) alongside the standards-compatible seconds claims, so a token minted a few milliseconds before the revocation is rejected — while one legitimately re-minted *after* it in that same second is still accepted.
152
151
  - **Fails closed:** a missing binding, a failed read, or a corrupt entry means the token's revocation state is *unknown* — and an unknown bearer is not authenticated. The caller gets `503 AUTH_REVOCATION_UNAVAILABLE` (RFC 9457, retryable). Recovery is a **separate cookie-only request**: a request carrying `Authorization` has its cookie stripped before session auth, so within that one request there is nothing left to fall back to. Reads are never silently skipped, because the outage that hides a revocation is exactly the moment this check exists for.
153
152
  - **Availability coupling:** the flip side of the above. Bearer-token auth now depends on KV being readable. Alert on `AUTH_REVOCATION_UNAVAILABLE`; a sustained rate means the binding is missing on some deployment target, or KV is degraded. Every named environment must declare `bindings.kv` — the compiler rejects a target that doesn't.
154
153
  - **Eventual consistency:** KV propagates cross-PoP in ~60s. "Immediate" means seconds at the writing location, bounded-seconds globally — still far inside the 15-minute carry-forward cap that bounds revocation without this check.
@@ -195,7 +194,7 @@ The `?redirect=…` query param is preserved unchanged so the central sign-in su
195
194
 
196
195
  Signing in is the *only* thing the CMS gate redirects for. A signed-in caller who isn't admitted is served the CMS shell and shown a screen naming what they'd need — see [CMS access](/ui/admin#access-gate). There is no wrong-role redirect, and no `auth.profileUrl`.
197
196
 
198
- > **Removed in v0.62:** `auth.profileUrl`. Its only consumer was the CMS wrong-role redirect. The config schema is strict, so a leftover `profileUrl` key now fails the compile — delete it.
197
+ > `auth.profileUrl` is not supported. The config schema is strict, so a `profileUrl` key fails the compile — delete it.
199
198
 
200
199
 
201
200
  ### Resolution precedence
@@ -280,7 +280,7 @@ EXTRA_APP_HOSTS = "app-preview.example.com,pr-42.example.com"
280
280
  wrangler secret put EXTRA_APP_HOSTS --env preview
281
281
  ```
282
282
 
283
- Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends all three allowlists — apps, CORS, and Better Auth's `trustedOrigins`. (Earlier v0.64 output stopped at the CORS layer: preflight passed, then Better Auth's own check rejected the origin. On older output, recompile — or set `BETTER_AUTH_URL` on the deploy target, since Better Auth always trusts its own base URL.)
283
+ Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends all three allowlists — apps, CORS, and Better Auth's `trustedOrigins`.
284
284
 
285
285
  > **Multi-app deploys**
286
286
  >
@@ -145,7 +145,7 @@ a compile error; delete that line and keep `routes`. See
145
145
  [API Contract](/platform/api-contract#contractversion-is-retired) for what
146
146
  changes if you were pinned to `version: "v1"`.
147
147
 
148
- Action input-schema fidelity is a compile gate since v0.63.0. The CLI must
148
+ Action input-schema fidelity is a compile gate. The CLI must
149
149
  successfully harvest `z.toJSONSchema(action.input)` for every authored action;
150
150
  partial or missing harvests fail with the exact action file keys, bundle or
151
151
  evaluation phase, and underlying local error. Dependencies are resolved from
@@ -433,7 +433,7 @@ action layer.
433
433
 
434
434
  Quickback manages four **audit columns** (`createdAt`, `modifiedAt`, `createdBy`, `modifiedBy`) on every feature table, plus two **soft-delete columns** (`deletedAt`, `deletedBy`) on tables whose resource uses soft delete (the default delete mode). The audit columns drive record-provenance queries and the CMS audit panel; the soft-delete pair drives soft-delete filtering.
435
435
 
436
- You declare them in the table's `columns` object with `...q.audit()` and `...q.softDelete()`. The compiler validates every managed column against its canonical shape and fails the compile when one is missing, diverges, or is present on a hard-delete table — run `quickback migrate visible-columns` to adopt the declarations on an existing project. Set `compiler.features.visibleAuditColumns: false` to downgrade those checks to warnings and keep the pre-v0.57.0 silent-injection behavior.
436
+ You declare them in the table's `columns` object with `...q.audit()` and `...q.softDelete()`. The compiler validates every managed column against its canonical shape and fails the compile when one is missing, diverges, or is present on a hard-delete table — run `quickback migrate visible-columns` to adopt the declarations on an existing project. Set `compiler.features.visibleAuditColumns: false` to downgrade those checks to warnings and silently inject the columns.
437
437
 
438
438
  To opt out of the managed columns entirely, project-wide:
439
439
 
@@ -485,7 +485,7 @@ export default defineConfig({
485
485
 
486
486
  If `signature.required: true` and no key is available, compilation fails with a clear error message (or warning in `failMode: "warn"`).
487
487
 
488
- ## Hostname architecture (v0.33+)
488
+ ## Hostname architecture
489
489
 
490
490
  A modern Quickback project runs on **one Cloudflare Worker** that serves multiple URL surfaces. By default, everything lives under a single unified backend hostname (auto-inferred as `quickback.{baseDomain}` from your other configured subdomains, or overridable via `config.domain`). For larger deployments, you can opt-in to **dedicated hostnames** for specific surfaces — they're additive aliases, never replacements.
491
491
 
@@ -515,7 +515,7 @@ For branding or operational separation, you can opt specific surfaces onto their
515
515
  cms: { domain: 'cms.example.com' },
516
516
  account: { domain: 'account.example.com' },
517
517
 
518
- // v0.33+ — backend surfaces on their own hosts:
518
+ // Backend surfaces on their own hosts:
519
519
  auth: { domain: 'auth.example.com' },
520
520
  api: { domain: 'api.example.com' },
521
521
 
@@ -118,7 +118,7 @@ The compiler applies these so config stays minimal:
118
118
  - **`X-Frame-Options` derives from `csp.frameAncestors`** (`['@none']` → `DENY`, contains `@self` → `SAMEORIGIN`, otherwise omitted — XFO can't represent arbitrary origins so CSP becomes the truth there). Override with `security.frameOptions`.
119
119
  - **`corp: 'same-origin'` is auto-emitted when `coep` is set.** `require-corp` without CORP breaks the ASSETS binding fetches on Cloudflare; the compiler couples them so users don't have to remember.
120
120
 
121
- ### CSP auto-config (0.10.15+)
121
+ ### CSP auto-config
122
122
 
123
123
  When you opt into a `csp` object, the compiler additively widens directives based on which Quickback features your project has enabled. **Additive** means anything you already wrote stays; we only push values that aren't already present.
124
124
 
@@ -140,7 +140,7 @@ font-src 'self' https://fonts.gstatic.com
140
140
  connect-src 'self' @trustedOrigins https://api.your-app.com
141
141
  ```
142
142
 
143
- Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened with style-only or connect-only hosts — that would let those hosts also reach `script-src` / `img-src` / `media-src` via fall-back, which is wider than the bundled SPA actually needs. (This rule changed in 0.10.17 — earlier versions incorrectly pushed additions into defaultSrc.)
143
+ Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened with style-only or connect-only hosts — that would let those hosts also reach `script-src` / `img-src` / `media-src` via fall-back, which is wider than the bundled SPA actually needs.
144
144
 
145
145
  **Visibility:** every applied addition prints to stderr at compile time — one line per addition with the directive, value, and reason. No silent magic. Loop's compile output now looks like:
146
146
 
@@ -155,7 +155,7 @@ Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened
155
155
 
156
156
  #### Why the SPA-baked origin shows up capitalised in CSP
157
157
 
158
- Projects with `domain: "..."` + bundled CMS / Account SPAs will see `connect-src 'self' https://Api.example.com …` in their served CSP — note the capital `A`. That's deliberate (added in 0.10.19) and works around a `wrangler dev` quirk, not a typo on our end.
158
+ Projects with `domain: "..."` + bundled CMS / Account SPAs will see `connect-src 'self' https://Api.example.com …` in their served CSP — note the capital `A`. That's deliberate and works around a `wrangler dev` quirk, not a typo on our end.
159
159
 
160
160
  `wrangler dev` rewrites the configured `custom_domain` host string in **every** response header value (Location, Content-Security-Policy, X-…) to the local hostname, with a case-sensitive substring matcher. Without the case-shift, the served CSP becomes `connect-src 'self' https://localhost:8787 …` and the bundled SPA's hardcoded `VITE_QUICKBACK_API_URL` fetches get blocked because the prod URL no longer appears in the allowlist.
161
161
 
@@ -100,7 +100,7 @@ any lowercase role name you reference in an access tree (`"recruiter"`,
100
100
  `"hiring-manager"`, `"support"`, …) is a custom org-membership role, matched
101
101
  against `ctx.roles` like the built-ins.
102
102
 
103
- As of v0.46, custom roles declared in access trees are **auto-registered
103
+ Custom roles declared in access trees are **auto-registered
104
104
  with the Better Auth organization plugin**, so members can actually be
105
105
  provisioned into them: `invite-member` and `update-member-role` accept them
106
106
  (previously they rejected custom roles with `400 ROLE_NOT_FOUND`).
@@ -132,6 +132,26 @@ interface Access {
132
132
  }
133
133
  ```
134
134
 
135
+ ### An empty list is a compile error
136
+
137
+ `roles: []`, `userRole: []`, and `principals: []` are refused at compile
138
+ time, on every access node — CRUD operations, `read`, views, actions, and
139
+ the arms of `or` / `and`. The runtime evaluator treats an empty list as
140
+ "no gate on this axis", so an arm that names nobody would admit **every
141
+ authenticated caller**. Masking uses the same literal the other way round
142
+ (`show: { roles: [] }` shows nobody), which is exactly why the compiler will
143
+ not guess here. Say what you mean:
144
+
145
+ {/* doc-compile: skip — config fragments, not a compilable project */}
146
+ ```typescript
147
+ create: { access: { userRole: ['sysadmin'] } } // closed to everyone but platform admins
148
+ // or omit `create` entirely — the route is not emitted
149
+ read: { access: { roles: ['AUTHENTICATED'] } } // every signed-in caller really is the audience
150
+ ```
151
+
152
+ Every empty arm in the project is listed in one compile error, so a project
153
+ fixes them all in one pass.
154
+
135
155
  ## `userRole` vs `roles`
136
156
 
137
157
  `roles` and `userRole` check **two different fields** and are often confused — get this wrong and you'll grant access too broadly.
@@ -200,7 +220,7 @@ access: { roles: ["PUBLIC"] }
200
220
  - `PUBLIC` skips authentication and role checks — anyone can call the endpoint
201
221
  - **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads, top-level writes (`create`/`update`/`delete`/`upsert`), views, and actions. The compiler trusts the marker; row-level safety comes from the firewall, masking, and (for token-gated endpoints like RSVP confirm, magic-link redemption, List-Unsubscribe-Post, webhook ingest) your handler's own validation. Anonymous write endpoints typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
202
222
  - **Firewall still applies** — data is scoped by the firewall (organization, owner, team)
203
- - **Tree semantics:** `PUBLIC` admits anonymous callers from anywhere in the access tree, not just a flat `roles` list. An `or:` arm containing `PUBLIC` admits anonymous callers past the authentication gate; an `and:` group admits them only when *every* arm does. The access, org, and firewall layers still evaluate the full tree afterwards. (Before v0.46 the emitted auth gate only honored `PUBLIC` in a flat `roles` list — a nested `PUBLIC` arm incorrectly answered `401`.)
223
+ - **Tree semantics:** `PUBLIC` admits anonymous callers from anywhere in the access tree, not just a flat `roles` list. An `or:` arm containing `PUBLIC` admits anonymous callers past the authentication gate; an `and:` group admits them only when *every* arm does. The access, org, and firewall layers still evaluate the full tree afterwards.
204
224
  - Every `PUBLIC` action invocation is **mandatory audit logged** to the security audit table (IP address, input, result, timing)
205
225
  - The wildcard `"*"` is **not supported** — using it throws a compile-time error
206
226
  - Tables with no isolation columns and any `PUBLIC` route do not require `firewall: [{ exception: true }]`
@@ -330,7 +350,7 @@ Use one of these instead:
330
350
 
331
351
  #### `SYSADMIN` — cross-tenant DB-admin tier
332
352
 
333
- Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platform sysadmins — the cross-tenant DB-admin tier introduced in v0.15.0. Compiles to `ctx.userRole === "sysadmin"`. **Requires `cms: { sysadmin: true }` on the project config**; without that flag, using `SYSADMIN` fails the compile so the role can't sit as dead code.
353
+ Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platform sysadmins — the cross-tenant DB-admin tier. Compiles to `ctx.userRole === "sysadmin"`. **Requires `cms: { sysadmin: true }` on the project config**; without that flag, using `SYSADMIN` fails the compile so the role can't sit as dead code.
334
354
 
335
355
  ```typescript
336
356
  // Cross-tenant audit dashboard, sysadmin-only
@@ -115,8 +115,8 @@ Zod 4's `z.toJSONSchema`. It does not call `execute`; the hosted compiler never
115
115
  evaluates project code. The output contract feeds OpenAPI and
116
116
  `Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
117
117
 
118
- **Every action input must produce a schema.** Since
119
- v0.63.0 a failed harvest fails the compile, naming the exact action, whether
118
+ **Every action input must produce a schema.** A failed harvest fails the
119
+ compile, naming the exact action, whether
120
120
  bundling or evaluation failed, and the underlying local error. Output remains
121
121
  optional.
122
122
 
@@ -17,7 +17,7 @@ POST /applications/:id/schedule-interview
17
17
  1. **Authentication** - User token is validated
18
18
  2. **Input Validation** - Request body validated against Zod schema
19
19
  3. **Role Gate** - The access roles are checked *before* the record is
20
- fetched (v0.46+), so a wrong-role caller gets a uniform
20
+ fetched, so a wrong-role caller gets a uniform
21
21
  `403 ACCESS_ROLE_REQUIRED` whether or not the record exists — the
22
22
  response can't be used to probe for record ids
23
23
  4. **Record Loading** - The record is fetched by ID **through the firewall**
@@ -420,4 +420,3 @@ imply "this writes data" — it's the right method whenever the request body is
420
420
  load-bearing. Use the response shape (`responseType: "json"`, or just the data
421
421
  your handler returns) to convey read semantics; HTTP method choice is about
422
422
  input transport, not action intent.
423
-
@@ -305,7 +305,7 @@ doubt: if only one folder's features reference it, it belongs in that folder's a
305
305
 
306
306
  When several standalone actions share a path prefix and the same relationship gate — `/event/:eventId/announce`, `/event/:eventId/cancel`, `/event/:eventId/respond` — declaring the gate per-action means writing the same `roles: ['attendee']` over and over AND paying the relationship-resolver cost N times per request (one subquery + one row-load, multiplied by the number of actions).
307
307
 
308
- Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware before the action's `execute()` runs. With the per-namespace helper (v0.27+, [below](#narrow-ctxexposeas-typing-v027)), that field is also statically typed as the loaded row.
308
+ Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware before the action's `execute()` runs. With the [per-namespace helper](#narrow-ctxexposeas-typing), that field is also statically typed as the loaded row.
309
309
 
310
310
  ### When to use roles vs. relationships
311
311
 
@@ -317,13 +317,13 @@ A user is authorized for a row when **any** of the following is true:
317
317
 
318
318
  Use **relationships** when membership is specific to *this row* — external collaborators who aren't in your org, attendees, anyone connected to the resource by virtue of data rather than payroll. Use **roles / team** when staff at your org/team should see everything in their scope by default.
319
319
 
320
- The two compose at the action level (`access.or` accepts both relationship-roles and tenant roles) and — as of v0.25 — at the namespace level too: `namespace.via` accepts an array of lanes, first match wins.
320
+ The two compose at the action level (`access.or` accepts both relationship-roles and tenant roles) and at the namespace level: `namespace.via` accepts an array of lanes, first match wins.
321
321
 
322
322
  > **Rule of thumb.** If the answer is *"yes if you work here,"* reach for org/team roles. If the answer is *"yes if you have something to do with **this** row,"* reach for a per-row relationship. Reach for both together — at the namespace or via `access.or` — when an action should let either side in.
323
323
 
324
324
  Two declaration sites depending on whether the participating actions live in one feature or many:
325
325
 
326
- ### Single feature: `defineTable({ namespace })` (v0.23+)
326
+ ### Single feature: `defineTable({ namespace })`
327
327
 
328
328
  Use when every action under the prefix lives in the same feature directory. The namespace travels with the table that owns it — no addition to `quickback.config.ts` needed.
329
329
 
@@ -366,9 +366,9 @@ export default defineAction({
366
366
 
367
367
  The compiler emits one `app.use(...)` on the events feature's Hono app. Every standalone action in `features/events/actions/` whose path starts with `/event/:eventId/` joins the namespace automatically.
368
368
 
369
- Multi-lane via (v0.25+) and bulk-grant lanes (v0.26+) work identically on the table-level declaration — `via:` accepts the same shapes documented below for the project-level form.
369
+ Multi-lane and bulk-grant lanes work identically on the table-level declaration — `via:` accepts the same shapes documented below for the project-level form.
370
370
 
371
- ### Cross-feature: `authz.namespaces` (v0.24+)
371
+ ### Cross-feature: `authz.namespaces`
372
372
 
373
373
  Use when the namespace spans multiple features. The declaration sits next to your other authz config in `quickback.config.ts`.
374
374
 
@@ -422,7 +422,7 @@ export default defineAction({
422
422
 
423
423
  The compiler emits one synthetic `src/routes/__namespace-event-scope.routes.ts` that imports each contributing feature's `actions` map under a distinct alias, mounts the resolver middleware once, and dispatches to the matching action. Worker-root mount order ensures the middleware fires before any per-feature route handler under the prefix.
424
424
 
425
- ### Multi-lane via (v0.25+) — first match wins
425
+ ### Multi-lane via — first match wins
426
426
 
427
427
  When more than one relationship can authorize a caller for the namespaced resource, pass `via:` as an array. The middleware tries each lane in declaration order and stops at the first match — `ctx.<exposeAs>` is hydrated from whichever lane fired.
428
428
 
@@ -458,9 +458,9 @@ authz: {
458
458
  }
459
459
  ```
460
460
 
461
- Hydration is **per matched lane** (v0.37+): each lane fills `ctx.<its own exposeAs>` from its own `loads:` table, so lanes may load different tables into different keys. Both lanes above name `events` / `event`, so `ctx.event` is populated whichever fires. A lane declaring neither `loads:` nor `exposeAs:` is authorization-only — it opens the gate and hydrates nothing.
461
+ Hydration is **per matched lane**: each lane fills `ctx.<its own exposeAs>` from its own `loads:` table, so lanes may load different tables into different keys. Both lanes above name `events` / `event`, so `ctx.event` is populated whichever fires. A lane declaring neither `loads:` nor `exposeAs:` is authorization-only — it opens the gate and hydrates nothing.
462
462
 
463
- ### Bulk-grant lanes (v0.26+)
463
+ ### Bulk-grant lanes
464
464
 
465
465
  Relationship lanes cover "specifically connected to this row." Bulk-grant lanes cover "anyone with this role / team membership in the row's tenant" — the case where an org admin or a team member should see every event in their scope without writing per-event relationship rows.
466
466
 
@@ -483,7 +483,7 @@ Each bulk-grant lane:
483
483
  - **`{ roles: [...] }`** — passes when the caller's BA org-role for the loaded resource's tenant includes any listed role. Short-circuits the relationship loop entirely; the role check is in-memory and cheap. Use for the "company admin sees everything" case.
484
484
  - **`{ team: true }`** — passes when `ctx.activeTeamId` is set. The loads-table firewall does the actual `events.teamId === ctx.activeTeamId` check during hydration. Use when the resource is team-scoped and you want active-team membership to grant access.
485
485
 
486
- Both bulk-grant lanes piggyback on the namespace's relationship lane(s) for hydration — they don't fetch a separate per-row subject; they just gate access and let the loads-table firewall handle the tenant scoping. **At least one relationship lane is required** alongside bulk-grant lanes in v0.26 (to anchor `loads:` + `exposeAs:`).
486
+ Both bulk-grant lanes piggyback on the namespace's relationship lane(s) for hydration — they don't fetch a separate per-row subject; they just gate access and let the loads-table firewall handle the tenant scoping. When a relationship lane anchors hydration, declare `loads:` + `exposeAs:` on that lane.
487
487
 
488
488
  When a request misses every lane, the 403 deny payload lists every authorization path the caller could have taken — relationship names, role names, and `"team-membership"` for `{ team: true }` lanes — so a developer debugging an unexpected 403 sees the full surface they need to satisfy.
489
489
 
@@ -497,7 +497,7 @@ Actions opt in by matching `path:` against a declared namespace prefix. There's
497
497
 
498
498
  Both forms share the same shape checks:
499
499
 
500
- - **`via:` accepts one of three shapes.** A single relationship name (v0.23+), an array of relationship names (v0.25+, first match wins), or — as of v0.26 — an array mixing relationship names with bulk-grant guards (`{ roles: [...] }`, `{ team: true }`). **A bare string is always a relationship name.** There is no string form for a role: `{ roles: [...] }` is a bulk-grant lane against Better Auth org roles, even when the name you put in it is a composed role defined `via` a relationship.
500
+ - **`via:` accepts one of three shapes.** A single relationship name, an array of relationship names (first match wins), or an array mixing relationship names with bulk-grant guards (`{ roles: [...] }`, `{ team: true }`). **A bare string is always a relationship name.** There is no string form for a role: `{ roles: [...] }` is a bulk-grant lane against Better Auth org roles, even when the name you put in it is a composed role defined `via` a relationship.
501
501
  - **Each relationship lane declares `loads` + `exposeAs`, or neither.** Both → the lane hydrates `ctx.<exposeAs>` from `loads` when it matches. Neither → an authorization-only lane. Exactly one is a compile error.
502
502
  - **Bulk-grant lanes inherit `loads:` + `exposeAs:` from sibling relationship lanes.** Pure bulk-grant namespaces (no relationship lane at all) are also accepted — set `loads:` + `exposeAs:` directly on the namespace declaration so hydration has somewhere to anchor.
503
503
  - **`prefix:` must contain at least one `:param` segment** (e.g. `/event/:eventId`). The middleware reads the relationship key from `c.req.param()` because no request body has been parsed at middleware time.
@@ -516,11 +516,11 @@ Inside a namespace action's `execute()`:
516
516
  - Tenant context (`ctx.activeOrgId` / `ctx.activeTeamId`) is stamped from the matched relationship row when its `from` table carries those columns. Downstream scoped queries work without further setup.
517
517
  - The action's own `access:` block (additional roles, userRole, record predicates, OTHER relationship arms) still runs after the namespace gate — namespace handles entry, per-action gates further.
518
518
 
519
- ### Narrow `ctx.<exposeAs>` typing (v0.27+)
519
+ ### Narrow `ctx.<exposeAs>` typing
520
520
 
521
- The namespace middleware hydrates `ctx.<exposeAs>` at runtime — that's been true since v0.23. The static type of that field, though, is `any` via the `AppContext` index signature: useful for not blocking access, but a missed opportunity for autocomplete and typo-catching.
521
+ The namespace middleware hydrates `ctx.<exposeAs>` at runtime. The static type of that field is `any` via the `AppContext` index signature: useful for not blocking access, but a missed opportunity for autocomplete and typo-catching.
522
522
 
523
- v0.27 emits one **per-namespace `defineAction` helper** alongside the standard `<feature>/.quickback/define-action.ts`. Importing from the narrowed helper retypes `ctx.<exposeAs>` inside `execute({ ctx })` to the loaded row's `$inferSelect` shape. Nothing else changes — runtime behavior, action discovery, and the `path:` namespace match are identical.
523
+ The compiler emits one **per-namespace `defineAction` helper** alongside the standard `<feature>/.quickback/define-action.ts`. Importing from the narrowed helper retypes `ctx.<exposeAs>` inside `execute({ ctx })` to the loaded row's `$inferSelect` shape. Nothing else changes — runtime behavior, action discovery, and the `path:` namespace match are identical.
524
524
 
525
525
  ```ts title="features/feeds/actions/feedMoments.ts"
526
526
  // One-line flip per namespace-scoped action:
@@ -549,7 +549,7 @@ The compiler emits one helper per `(feature, namespace)` pair where the feature
549
549
 
550
550
  #### Opt-in, not breaking
551
551
 
552
- Actions that keep their existing `import { defineAction } from '../.quickback/define-action'` continue to compile unchanged — `ctx.<exposeAs>` is `any` via the `AppContext` index signature, which is exactly the v0.23–v0.26 behavior. You flip imports per action at your own pace.
552
+ Actions that import `defineAction` from `../.quickback/define-action` compile with `ctx.<exposeAs>` as `any` via the `AppContext` index signature. Use the per-namespace helper for the narrowed type.
553
553
 
554
554
  #### Compile-time advisory
555
555
 
@@ -578,4 +578,3 @@ src/features/interviews/.quickback/
578
578
  #### Why per-namespace and not per-action
579
579
 
580
580
  A `defineAction` helper that's narrow to *one* exposed key (the namespace's `exposeAs`) is enough — every action under a namespace sees the same hydrated key. The alternative (per-action emit) duplicates the same prelude N times for the same shape; per-namespace keeps emission proportional to the number of distinct hydration shapes in the project.
581
-
@@ -64,6 +64,11 @@ the operations manifest.
64
64
  update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
65
65
  ```
66
66
 
67
+ The registry records these ops in `routesDisabled`, so the
68
+ [CMS](/ui/admin/owned-records) suppresses raw-CRUD buttons for them while
69
+ still rendering the relation inline on the root's record page — its writes
70
+ are changeset ops, which `routes: false` deliberately leaves open.
71
+
67
72
  ## The wire contract
68
73
 
69
74
  One blessed path — **RFC 5789 media-type dispatch** on the routes you already