@quickback-dev/cli 0.66.5 → 0.66.7

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 (109) hide show
  1. package/README.md +0 -1
  2. package/dist/index.js +1 -1
  3. package/dist/lib/api-client.d.ts +1 -1
  4. package/dist/lib/api-client.d.ts.map +1 -1
  5. package/dist/lib/api-client.js +13 -8
  6. package/dist/lib/api-client.js.map +1 -1
  7. package/dist/lib/api-client.test.js +47 -0
  8. package/dist/lib/api-client.test.js.map +1 -1
  9. package/dist/lib/migrations/drizzle.d.ts.map +1 -1
  10. package/dist/lib/migrations/drizzle.js +6 -1
  11. package/dist/lib/migrations/drizzle.js.map +1 -1
  12. package/dist/lib/migrations/drizzle.test.js +7 -0
  13. package/dist/lib/migrations/drizzle.test.js.map +1 -1
  14. package/dist/lib/migrations/executor.d.ts.map +1 -1
  15. package/dist/lib/migrations/executor.js +4 -0
  16. package/dist/lib/migrations/executor.js.map +1 -1
  17. package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts +7 -0
  18. package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts.map +1 -0
  19. package/dist/lib/migrations/postprocessors/better-auth-upgrade.js +149 -0
  20. package/dist/lib/migrations/postprocessors/better-auth-upgrade.js.map +1 -0
  21. package/dist/skill/SKILL.md +0 -2
  22. package/dist/skill/docs/api/openapi.md +1 -1
  23. package/dist/skill/docs/configure/auth.md +4 -5
  24. package/dist/skill/docs/configure/domains.md +1 -1
  25. package/dist/skill/docs/configure/index.md +4 -4
  26. package/dist/skill/docs/configure/security.md +3 -3
  27. package/dist/skill/docs/define/access.md +23 -3
  28. package/dist/skill/docs/define/actions/defining.md +2 -2
  29. package/dist/skill/docs/define/actions/index.md +6 -0
  30. package/dist/skill/docs/define/actions/record-and-standalone.md +1 -2
  31. package/dist/skill/docs/define/areas.md +14 -15
  32. package/dist/skill/docs/define/changesets.md +5 -0
  33. package/dist/skill/docs/define/diagnostics.md +2 -2
  34. package/dist/skill/docs/define/fga.md +1 -1
  35. package/dist/skill/docs/define/firewall.md +5 -5
  36. package/dist/skill/docs/define/guards.md +2 -1
  37. package/dist/skill/docs/define/masking.md +2 -2
  38. package/dist/skill/docs/define/relationships.md +8 -10
  39. package/dist/skill/docs/define/scopes.md +1 -1
  40. package/dist/skill/docs/define/transitions.md +11 -0
  41. package/dist/skill/docs/define/triggers.md +4 -0
  42. package/dist/skill/docs/index.md +0 -6
  43. package/dist/skill/docs/platform/auth/index.md +37 -0
  44. package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -2
  45. package/dist/skill/docs/platform/queues/handlers.md +12 -0
  46. package/dist/skill/docs/platform/realtime/durable-objects.md +1 -1
  47. package/dist/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
  48. package/dist/skill/docs/platform/schedules/index.md +3 -1
  49. package/dist/skill/docs/platform/webhooks/inbound.md +1 -1
  50. package/dist/skill/docs/tooling/claude-skill.md +0 -7
  51. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +11 -1
  52. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +16 -0
  53. package/dist/skill/docs/tooling/output.md +7 -6
  54. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  55. package/dist/skill/docs/ui/account/features/organizations.md +1 -1
  56. package/dist/skill/docs/ui/admin/index.md +1 -1
  57. package/dist/skill/docs/ui/admin/owned-records.md +81 -0
  58. package/dist/skill/docs/ui/admin/schema-format.md +16 -0
  59. package/package.json +1 -1
  60. package/src/skill/SKILL.md +0 -2
  61. package/src/skill/docs/api/openapi.md +1 -1
  62. package/src/skill/docs/configure/auth.md +4 -5
  63. package/src/skill/docs/configure/domains.md +1 -1
  64. package/src/skill/docs/configure/index.md +4 -4
  65. package/src/skill/docs/configure/security.md +3 -3
  66. package/src/skill/docs/define/access.md +23 -3
  67. package/src/skill/docs/define/actions/defining.md +2 -2
  68. package/src/skill/docs/define/actions/index.md +6 -0
  69. package/src/skill/docs/define/actions/record-and-standalone.md +1 -2
  70. package/src/skill/docs/define/areas.md +14 -15
  71. package/src/skill/docs/define/changesets.md +5 -0
  72. package/src/skill/docs/define/diagnostics.md +2 -2
  73. package/src/skill/docs/define/fga.md +1 -1
  74. package/src/skill/docs/define/firewall.md +5 -5
  75. package/src/skill/docs/define/guards.md +2 -1
  76. package/src/skill/docs/define/masking.md +2 -2
  77. package/src/skill/docs/define/relationships.md +8 -10
  78. package/src/skill/docs/define/scopes.md +1 -1
  79. package/src/skill/docs/define/transitions.md +11 -0
  80. package/src/skill/docs/define/triggers.md +4 -0
  81. package/src/skill/docs/index.md +0 -6
  82. package/src/skill/docs/platform/auth/index.md +37 -0
  83. package/src/skill/docs/platform/auth/jwt-optimization.md +2 -2
  84. package/src/skill/docs/platform/queues/handlers.md +12 -0
  85. package/src/skill/docs/platform/realtime/durable-objects.md +1 -1
  86. package/src/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
  87. package/src/skill/docs/platform/schedules/index.md +3 -1
  88. package/src/skill/docs/platform/webhooks/inbound.md +1 -1
  89. package/src/skill/docs/tooling/claude-skill.md +0 -7
  90. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +11 -1
  91. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +16 -0
  92. package/src/skill/docs/tooling/output.md +7 -6
  93. package/src/skill/docs/ui/account/features/admin.md +1 -1
  94. package/src/skill/docs/ui/account/features/organizations.md +1 -1
  95. package/src/skill/docs/ui/admin/index.md +1 -1
  96. package/src/skill/docs/ui/admin/owned-records.md +81 -0
  97. package/src/skill/docs/ui/admin/schema-format.md +16 -0
  98. package/dist/skill/docs/changelog/index.md +0 -945
  99. package/dist/skill/docs/changelog/v0.1x.md +0 -1202
  100. package/dist/skill/docs/changelog/v0.2x.md +0 -589
  101. package/dist/skill/docs/changelog/v0.3x.md +0 -1152
  102. package/dist/skill/docs/changelog/v0.4x.md +0 -1108
  103. package/dist/skill/docs/changelog/v0.5x.md +0 -885
  104. package/src/skill/docs/changelog/index.md +0 -945
  105. package/src/skill/docs/changelog/v0.1x.md +0 -1202
  106. package/src/skill/docs/changelog/v0.2x.md +0 -589
  107. package/src/skill/docs/changelog/v0.3x.md +0 -1152
  108. package/src/skill/docs/changelog/v0.4x.md +0 -1108
  109. package/src/skill/docs/changelog/v0.5x.md +0 -885
@@ -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
@@ -26,7 +26,7 @@ The first line stays greppable (`[quickback:<channel>] CODE: message`); the
26
26
  source location, fix hint, and — for promoted errors — the exact override
27
27
  recipe render on continuation lines.
28
28
 
29
- ## Errors vs warnings (v0.47+)
29
+ ## Errors vs warnings
30
30
 
31
31
  The checks split into two tiers:
32
32
 
@@ -114,7 +114,7 @@ authz: {
114
114
  {
115
115
  check: 'AUTHZ_CAPABILITY_CEILING',
116
116
  target: 'sessions/scope:event:organizer',
117
- reason: 'organizer grant profile lands with the v2 rollout (TICKET-123)',
117
+ reason: 'temporary exception while the organizer grant profile is implemented',
118
118
  },
119
119
  ],
120
120
  },
@@ -307,7 +307,7 @@ stored tuple whose subject shape isn't allowed for the relation is inert. So a
307
307
  `user:*` tuple on a relation declared `[user]` (no wildcard) can never grant
308
308
  access, even if it was written out-of-band — the model is the ceiling.
309
309
 
310
- ## Limitations (v0.35)
310
+ ## Limitations
311
311
 
312
312
  - `access: { fga }` covers **per-record** operations (`GET /:id`, `update`,
313
313
  `delete`, record-based actions) and **collection filtering** on
@@ -100,9 +100,9 @@ type FirewallPredicate =
100
100
  | { field: string; isNull: true } // column IS NULL
101
101
  | { field: string; in: string[] | string; optional?: boolean } // column IN (...)
102
102
  | { field: string; via: string } // column IN (relationship subquery)
103
- | { field?: string; permission: string } // named authz.permissions reference (v0.35+)
104
- | { all: FirewallPredicate[] } // AND group (v0.35+)
105
- | { any: FirewallPredicate[] } // OR group (v0.35+)
103
+ | { field?: string; permission: string } // named authz.permissions reference
104
+ | { all: FirewallPredicate[] } // AND group
105
+ | { any: FirewallPredicate[] } // OR group
106
106
  | { exception: true }; // opt out of tenant scoping
107
107
 
108
108
  type FirewallConfig = ReadonlyArray<FirewallPredicate>;
@@ -113,7 +113,7 @@ firewallErrorMode?: 'reveal' | 'hide';
113
113
 
114
114
  The top-level array is AND'd together. `firewallErrorMode` lives at the resource top level — it's a presentation-layer choice (403 vs 404), not a query-shape one.
115
115
 
116
- ## Boolean groups: `all` / `any` (v0.35+)
116
+ ## Boolean groups: `all` / `any`
117
117
 
118
118
  A flat array can only express AND. To grant access through **either** of two independent paths — "an org member **OR** an event attendee" — nest an `any` group. The top-level array stays sugar for `all`, so every existing firewall is byte-identical.
119
119
 
@@ -389,7 +389,7 @@ So `firewall: [{ exception: true }]` on the default configuration returns `isNul
389
389
 
390
390
  ## Sysadmin Escape Hatch
391
391
 
392
- When `cms: { sysadmin: true }` is set on the project (introduced in v0.15.0), every `buildFirewallConditions()` emits a runtime branch that drops tenant scopes for `ctx.userRole === 'sysadmin'` callers while keeping the soft-delete predicate:
392
+ When `cms: { sysadmin: true }` is set on the project, every `buildFirewallConditions()` emits a runtime branch that drops tenant scopes for `ctx.userRole === 'sysadmin'` callers while keeping the soft-delete predicate:
393
393
 
394
394
  ```typescript
395
395
  // Generated for an org-scoped table when cms.sysadmin: true
@@ -76,7 +76,8 @@ guards: {
76
76
  > to the table for `db.update(<table>).set({ … })` / `db.insert(<table>).values({ … })`
77
77
  > and refuses an `immutable` column in any update, or a `protected` column
78
78
  > written by an action that is not in its list — with an error naming the action,
79
- > the column, and the fix. The two tiers are therefore distinct: `immutable` is
79
+ > the column, and the fix. Every offending action in the project is listed in
80
+ > that one error, so a single compile surfaces all of them. The two tiers are therefore distinct: `immutable` is
80
81
  > written once at create and never again; if a column needs an action to change
81
82
  > it, it is `protected`, mapped to that action.
82
83
  >
@@ -50,7 +50,7 @@ Whether `customers.email` is PII to hide or the display label of a contact list
50
50
 
51
51
  So the compiler asks. A false positive costs you one line (`cc: false`) — which is also a durable, reviewable record that somebody looked.
52
52
 
53
- It also removes a bug class outright. When detection can never quietly supply a rule, the set of masked columns is the set you declared, so no two surfaces can disagree about it. That exact disagreement was a real defect: through v0.58.3 the response path applied declared-only masking while realtime and live views applied detected-plus-declared, so an auto-detected secret was redacted over WebSocket and returned in **plaintext** on `GET`.
53
+ It also removes a bug class outright. When detection can never quietly supply a rule, the set of masked columns is the set you declared, so no two surfaces can disagree about it.
54
54
 
55
55
  ### What a decision controls
56
56
 
@@ -215,7 +215,7 @@ masking: {
215
215
  }
216
216
  ```
217
217
 
218
- `show: { roles: [] }` has the same effect, but it doesn't say the same thing. An empty role list reads as an oversight, and it is also what authors fall back to when the audience they wanted is **inexpressible** — masking gates on org and scoped roles, so a table gated `access: { userRole: ['sysadmin'] }` cannot name its own audience in a mask. Two different intentions, one spelling, and no way for the next reader to tell them apart.
218
+ `show: { roles: [] }` has the same effect, but it doesn't say the same thing. An empty role list reads as an oversight, and it is also what authors fall back to when the audience they wanted is **inexpressible** — masking gates on org and scoped roles, so a table gated `access: { userRole: ['sysadmin'] }` cannot name its own audience in a mask. Two different intentions, one spelling, and no way for the next reader to tell them apart. Note the asymmetry with access, where an empty list would mean *everyone* — which is why [access refuses it at compile time](/define/access#an-empty-list-is-a-compile-error).
219
219
 
220
220
  Write `'never'` when nobody is the intent. Any other string is a compile error rather than a guess — `show: 'admin'` is a plausible typo, and masking-for-everyone is the wrong thing to assume from it.
221
221
 
@@ -118,7 +118,7 @@ the compiler rejects a relationship-bearing `masking.show` rule and points to a
118
118
  relationship-gated view instead. It never drops the relationship arm or turns
119
119
  it into a broader role grant.
120
120
 
121
- ### Standalone actions: surface keys and `loads` / `exposeAs` (v0.19+)
121
+ ### Standalone actions: surface keys and `loads` / `exposeAs`
122
122
 
123
123
  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.
124
124
 
@@ -132,7 +132,7 @@ authz: {
132
132
  subject: { column: 'userId', equals: 'ctx.userId' },
133
133
  resource: { column: 'eventId' },
134
134
  where: { status: 'confirmed' },
135
- loads: 'events', // ← v0.19+: load matching event row
135
+ loads: 'events', // load matching event row
136
136
  exposeAs: 'event', // ← onto ctx.event for the action body
137
137
  },
138
138
  },
@@ -142,7 +142,7 @@ authz: {
142
142
  }
143
143
  ```
144
144
 
145
- The resolver (v0.20):
145
+ The resolver:
146
146
 
147
147
  1. **Cheap in-memory role check** first — `ctx.roles?.includes('admin')` and friends. If the caller has a qualifying role, this short-circuits and no DB queries fire for the access gate.
148
148
  2. **Firewall-gated relationship match** if the role check failed — `SELECT { organizationId, teamId } FROM guests WHERE userId=ctx.userId AND eventId=input.eventId AND status='confirmed'` with the `guests` table's full firewall AND-applied. If neither role nor relationship qualifies → 403.
@@ -152,24 +152,22 @@ The resolver (v0.20):
152
152
 
153
153
  **No firewall bypass anywhere.** Both queries run with their respective tables' full firewalls. The relationship row's existence is the proof that the caller is authorized; its tenant columns are the source of the stamped claim.
154
154
 
155
- ### Conditional tenant preconditions (v0.20+)
155
+ ### Conditional tenant preconditions
156
156
 
157
- Standalone actions in features with org/team-scoped tables previously emitted unconditional preconditions:
157
+ Standalone actions in features with org/team-scoped tables emit tenant preconditions only when a relationship cannot supply the tenant:
158
158
 
159
159
  ```ts
160
160
  if (!ctx.activeOrgId) return c.json(AccessErrors.noOrg(), 403);
161
161
  if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
162
162
  ```
163
163
 
164
- These ran **before** the relationship resolver, which 403'd attendees whose sessions don't carry an active tenant claim (the canonical event-attendee shape).
165
-
166
- v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before. `ADMIN` is now rejected at compile time.
164
+ If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` also bypass the preconditions. `ADMIN` is rejected at compile time.
167
165
 
168
166
  Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
169
167
 
170
168
  ### Requirement on the relationship's `from` table
171
169
 
172
- For the v0.20 tenant-stamping to work, the relationship's `from` table must carry tenant columns:
170
+ For tenant-stamping to work, the relationship's `from` table must carry tenant columns:
173
171
 
174
172
  - For org stamping: an `organizationId` column (or whatever spelling the project's auth-provider defaults pick).
175
173
  - For team stamping: a `teamId` column.
@@ -213,7 +211,7 @@ export default defineAction({
213
211
 
214
212
  `loads` and `exposeAs` are co-required (set both or neither). `exposeAs` must be a valid JS identifier and must not collide with built-in `ctx` fields (`userId`, `activeOrgId`, `activeTeamId`, `db`, etc.).
215
213
 
216
- ### Action firewall escape hatch (v0.19+)
214
+ ### Action firewall escape hatch
217
215
 
218
216
  `defineAction({ firewall: { exception: true } })` opts the action out of the inherited session-key preconditions (`ctx.activeOrgId` / `ctx.activeTeamId` requirements) AND the relationship resolver. The handler receives `unsafeDb` for raw Drizzle access. Use for cross-tenant or admin routes whose surface intentionally doesn't name a session/relationship key:
219
217
 
@@ -672,7 +672,7 @@ The scope claim is trusted between proofs — it is never re-checked against the
672
672
 
673
673
  So removing a guest/staff row takes effect within **cap + one TTL** for a client that keeps polling, and within one TTL once it goes idle. Two ways to tighten that:
674
674
 
675
- - **`auth.jwt.revocationCheck: 'kv'`** (v0.45+, Cloudflare runtime) — sub-TTL revocation: updating or deleting a conferring relationship row stamps a revocation timestamp in KV, and the bearer fast-path rejects a carried scope claim whose proof is at or before it — no same-second gap. Each kind is compared against **its own** proof time (`sctMs` on the entry; older tokens without one fall back to the token-level `sct`/`sctMs`), so a mint of one kind can't carry a revoked kind past its marker. Neither the refresh nor a re-mint ever substitutes its own clock for a proof it didn't take. The check fails closed — a scope claim whose revocation state can't be read is not trusted either. See [auth config](/configure/auth).
675
+ - **`auth.jwt.revocationCheck: 'kv'`** (Cloudflare runtime) — sub-TTL revocation: updating or deleting a conferring relationship row stamps a revocation timestamp in KV, and the bearer fast-path rejects a carried scope claim whose proof is at or before it — no same-second gap. Each kind is compared against **its own** proof time (`sctMs` on the entry; tokens without one fall back to the token-level `sct`/`sctMs`), so a mint of one kind can't carry a revoked kind past its marker. Neither the refresh nor a re-mint ever substitutes its own clock for a proof it didn't take. The check fails closed — a scope claim whose revocation state can't be read is not trusted either. See [auth config](/configure/auth).
676
676
  - **`via` arms** — for tables where any caching is too wide, gate with a `via` arm instead of a bare `ctx.scope.<kind>` arm: `via` emits a live subquery against the relationship table on every request, immune to a stale claim entirely.
677
677
 
678
678
  ## Reference
@@ -15,6 +15,17 @@ Two declaration sites:
15
15
  idempotency, and compiler-applied writes, for an action you are writing
16
16
  anyway.
17
17
 
18
+ Both work on **any table in the feature** — the primary and its siblings
19
+ alike. A sibling table's transitions synthesize to
20
+ `actions/<table>/<name>.ts`, bound to that table, importing the generated
21
+ per-table helper (`.quickback/define-action.<table>`), and mount at
22
+ `POST /<table>/:id/<name>` exactly like a primary's. So a status machine on a
23
+ child table (`reservations` inside `features/sessions/`) does not force the
24
+ table into its own feature — group related tables freely. Never replace
25
+ declared transitions with hand-written per-verb actions: you lose the
26
+ generated routes, the `guards.protected` integration, and the CMS
27
+ affordances.
28
+
18
29
  ## Two lines per state change
19
30
 
20
31
  ```typescript
@@ -78,6 +78,10 @@ the next migrate.
78
78
  - `OLD.column` / `NEW.column` references use **SQL column names**
79
79
  (`deleted_at`, not `deletedAt`) and are validated against the table at
80
80
  compile time.
81
+ - Bare `CASE ... END` expressions, including nested cases, are supported.
82
+ For example: `SELECT CASE WHEN NEW.total < 0 THEN RAISE(ABORT, 'invalid total') END;`.
83
+ That `END` closes the expression; authored `BEGIN ... END` trigger frames
84
+ are rejected.
81
85
  - Optional `when:` is a SQL expression guard (`WHEN` clause).
82
86
  - To reject a write, `SELECT RAISE(ABORT, 'message');` — this is the only
83
87
  trigger form that blocks *every* write path, including raw SQL.
@@ -76,9 +76,3 @@ The runtime services around your compiled code. Everything you need for a comple
76
76
  - **[Account UI](/ui/account)** — Pre-built auth and profile pages
77
77
 
78
78
  Everything runs on **your own Cloudflare account** — no Quickback infrastructure between you and your data.
79
-
80
- ---
81
-
82
- ### Changelog
83
-
84
- [**Changelog**](/changelog) — what's new in Quickback. Release notes, new features, and improvements.
@@ -62,3 +62,40 @@ Roles are used throughout the security layers — in [Access](/define/access) ru
62
62
 
63
63
  - [Plugins](/platform/auth/plugins) — Email OTP, passkeys, magic links, and more
64
64
  - [Security](/platform/auth/security) — Cookies, rate limiting, cross-domain auth
65
+
66
+ ## Compiler-managed auth versions and upgrades
67
+
68
+ The compiler pins Better Auth, its schema CLI, and the generated companion
69
+ packages to **1.7.2**. Recompile and install the emitted dependencies together;
70
+ remove older Better Auth overrides from `build.dependencies`. An incompatible
71
+ override is rejected because it would run a different auth version from the
72
+ one that generated your schema.
73
+
74
+ For an existing project, retain its `quickback/drizzle` migration history and
75
+ use the updated CLI when recompiling. The CLI generates the upgrade locally;
76
+ migration history stays on your machine. Apply the newly generated auth migration before
77
+ starting the updated Worker. Existing migration SQL is preserved. The upgrade
78
+ adds the current JWT/OAuth schema, including JWKS `alg`/`crv` and resource-bound
79
+ grants, and backfills account identities without resetting credentials.
80
+
81
+ Automatic account backfill covers password, SIWE, Google, Apple, Facebook,
82
+ Line, GitHub, and compiler-managed Cloudflare accounts. Unknown/custom provider
83
+ identities and duplicate identities must be resolved with an explicit migration;
84
+ the generated migration fails before replacing existing account rows. Custom
85
+ foreign keys into SQLite's account table also require an explicit migration.
86
+ Rehearse the migration against a database copy, and stop old auth writers during
87
+ the cutover so they cannot write the previous account shape.
88
+
89
+ Existing OAuth grants without a recorded resource set are revoked during the
90
+ upgrade; clients must authorize again. Client registrations and ordinary
91
+ sessions are retained. The compiler maps its audience configuration into the
92
+ 1.7 `resources` option and preserves the previous global resource allowlist
93
+ for clients (`enforcePerClientResources: false`). Authorization-code and refresh
94
+ grants still bind resources and reject widening to an unauthorized resource.
95
+ Projects opting into per-client resource restrictions must link their clients
96
+ to resources using the OAuth provider's resource administration APIs.
97
+
98
+ The bundled Account UI uses `signIn.social` and `linkSocial` for generic OAuth
99
+ providers, including Cloudflare. Their callback is now
100
+ `/auth/v1/callback/cloudflare`; update the registered redirect URI when upgrading
101
+ an existing Cloudflare login integration.
@@ -110,7 +110,7 @@ The fast-path is stateless by default: it verifies the signature and **trusts th
110
110
 
111
111
  **Lower the TTL.** `auth.jwt.expiresIn: 30` gives a hard 30-second ceiling. Browser SPAs auto-refresh via `set-auth-token` on every authed call, so a low TTL is invisible to logged-in users; only stale server-to-server bearer tokens feel it.
112
112
 
113
- **Or enable sub-TTL revocation.** Set `revocationCheck: 'kv'` (v0.45+, Cloudflare runtime only):
113
+ **Or enable sub-TTL revocation.** Set `revocationCheck: 'kv'` (Cloudflare runtime only):
114
114
 
115
115
  ```ts title="quickback.config.ts"
116
116
  auth: {
@@ -120,7 +120,7 @@ auth: {
120
120
 
121
121
  The fast-path then consults per-principal revocation timestamps in your project's existing `KV` binding (keys prefixed `qbrev:`, self-expiring) *before* trusting a token. A token is rejected when its mint timestamp (`iat`/`iatMs`, or the proof time of the scope kind being checked) is **at or before** the stored timestamp. Cost: 2+ edge-cached KV reads per bearer verify.
122
122
 
123
- There is no same-second gap: markers are epoch milliseconds (written `m<ms>`, v0.61.0+), tokens carry millisecond companions, and the comparison denies a tie — 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. Pre-v0.61.0 workers don't understand that marker format and read it as "not revoked" — don't roll back across the upgrade or share one KV namespace between versions; see [`revocationCheck`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy).
123
+ There is no same-second gap: markers are epoch milliseconds (written `m<ms>`), tokens carry millisecond companions, and the comparison denies a tie — 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.
124
124
 
125
125
  Revocation stamps are written **automatically** on:
126
126
 
@@ -150,6 +150,13 @@ The compiler:
150
150
  2. Extracts top-level `const` declarations (including multi-line template literals)
151
151
  3. Inlines them in the generated queue consumer
152
152
 
153
+ Write static relative imports from your authored file's location. For example,
154
+ from `quickback/services/queues/ingest.ts`, import a feature helper with
155
+ `../../features/materials/lib/process`. The compiler relocates that import to
156
+ `./features/materials/lib/process` in `src/queue-consumer.ts`. Multiline imports
157
+ and mixed value/type imports retain their declarations. Package imports keep
158
+ their package specifiers.
159
+
153
160
  ## Dynamic Schema Imports
154
161
 
155
162
  Since your schema files are generated by Quickback, use dynamic imports to reference them:
@@ -170,6 +177,11 @@ execute: async ({ message, db }) => {
170
177
 
171
178
  ## Sending to Other Queues
172
179
 
180
+ Queue producers configured through the database's `additionalQueues` or
181
+ `bindings.queueProducers` are included in generated `CloudflareBindings` as
182
+ `Queue` bindings, including `send` and `sendBatch`. They are available from
183
+ schedules and actions as well as queue handlers.
184
+
173
185
  Chain queue handlers by sending messages to other queues:
174
186
 
175
187
  ```typescript
@@ -367,7 +367,7 @@ await realtime.update('applications', newRecord, oldRecord, ctx.activeOrgId!, {
367
367
  });
368
368
  ```
369
369
 
370
- **Fail-closed (v0.48+):** an omitted or empty `targetRoles` delivers to
370
+ **Fail-closed:** an omitted or empty `targetRoles` delivers to
371
371
  **nobody** — there is no implicit "everyone" fallback. To reach every
372
372
  authenticated subscriber in the scope, say so explicitly with
373
373
  `targetRoles: ['AUTHENTICATED']`. UPPERCASE pseudo-roles (`PUBLIC`,
@@ -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
 
@@ -124,7 +124,9 @@ The generated `scheduled()` dispatcher runs every schedule whose cron matches `e
124
124
 
125
125
  ## Cron syntax
126
126
 
127
- Standard Cloudflare cron (`minute hour day-of-month month day-of-week`):
127
+ Standard Cloudflare cron (`minute hour day-of-month month day-of-week`). Step
128
+ expressions such as `*/5 * * * *` are supported directly; the generated runner
129
+ preserves the exact expression for dispatch:
128
130
 
129
131
  | Pattern | Runs |
130
132
  |---------|------|
@@ -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
 
@@ -119,3 +119,13 @@ On failure, an `error` event is emitted in either protocol:
119
119
  event: error
120
120
  data: { "error": "Compilation failed", "code": "...", "message": "..." }
121
121
  ```
122
+
123
+ `message` is a **hit list, not a single error**. Independent validation
124
+ failures across features and tables are collected and reported together —
125
+ when more than one exists, the message opens with
126
+ `Found N independent errors — fix ALL of them before recompiling:` followed by
127
+ a numbered list. Fix every entry before recompiling; fixing only the first and
128
+ recompiling wastes a round trip. (Errors from different compile phases — e.g.
129
+ a feature that fails to parse and a resource-config violation — can still
130
+ arrive in successive compiles, since a feature that doesn't parse can't have
131
+ its resource config validated.)
@@ -13,6 +13,22 @@ quickback login
13
13
 
14
14
  Large projects may take longer to compile. The cloud compiler uses [Cloudflare Containers](https://developers.cloudflare.com/containers/) to run compilation in isolated environments. If you hit timeouts, try [running the compiler locally](/tooling/cloud-compiler/local-compiler).
15
15
 
16
+ ## Compiler stays on loading
17
+
18
+ The cloud gateway checks the compiler container with a five-second deadline.
19
+ A container that is warming or does not answer reports `status: "loading"`;
20
+ `status: "ready"` requires the compiler itself to report readiness. The CLI
21
+ limits each health request to ten seconds and retries within a four-minute
22
+ elapsed-time budget before reporting an error. These limits include response
23
+ body reads, so a stalled connection cannot leave the CLI waiting indefinitely.
24
+
25
+ A successful container lifecycle check alone does not prove compilation works.
26
+ After restarting or replacing an unhealthy instance, check `/health` and compile
27
+ an example project. If HTTP remains unresponsive, inspect Cloudflare container
28
+ logs and networking rather than repeatedly restarting the same instance. You
29
+ can use the [local Docker compiler](/tooling/cloud-compiler/local-compiler) while
30
+ the hosted service is unavailable.
31
+
16
32
  ## "Command not found: quickback"
17
33
 
18
34
  Make sure the CLI is installed globally:
@@ -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