@quickback-dev/cli 0.55.0 → 0.55.1

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 (95) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +41 -4
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/create.d.ts.map +1 -1
  5. package/dist/commands/create.js +5 -1
  6. package/dist/commands/create.js.map +1 -1
  7. package/dist/docs/content.d.ts.map +1 -1
  8. package/dist/docs/content.js +37 -22
  9. package/dist/docs/content.js.map +1 -1
  10. package/dist/index.js +1 -1
  11. package/dist/lib/action-harvest.d.ts +16 -1
  12. package/dist/lib/action-harvest.d.ts.map +1 -1
  13. package/dist/lib/action-harvest.js +21 -1
  14. package/dist/lib/action-harvest.js.map +1 -1
  15. package/dist/lib/action-harvest.test.js +122 -3
  16. package/dist/lib/action-harvest.test.js.map +1 -1
  17. package/dist/lib/api-client.d.ts +11 -0
  18. package/dist/lib/api-client.d.ts.map +1 -1
  19. package/dist/lib/api-client.js.map +1 -1
  20. package/dist/lib/artifact-routing.d.ts.map +1 -1
  21. package/dist/lib/artifact-routing.js +3 -0
  22. package/dist/lib/artifact-routing.js.map +1 -1
  23. package/dist/lib/compiler-floor.d.ts +39 -0
  24. package/dist/lib/compiler-floor.d.ts.map +1 -0
  25. package/dist/lib/compiler-floor.js +75 -0
  26. package/dist/lib/compiler-floor.js.map +1 -0
  27. package/dist/lib/compiler-floor.test.d.ts +2 -0
  28. package/dist/lib/compiler-floor.test.d.ts.map +1 -0
  29. package/dist/lib/compiler-floor.test.js +67 -0
  30. package/dist/lib/compiler-floor.test.js.map +1 -0
  31. package/dist/lib/compiler-stubs.d.ts +6 -0
  32. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  33. package/dist/lib/compiler-stubs.js +8 -0
  34. package/dist/lib/compiler-stubs.js.map +1 -1
  35. package/dist/lib/file-loader.d.ts +45 -4
  36. package/dist/lib/file-loader.d.ts.map +1 -1
  37. package/dist/lib/file-loader.js +116 -19
  38. package/dist/lib/file-loader.js.map +1 -1
  39. package/dist/lib/file-loader.test.js +80 -4
  40. package/dist/lib/file-loader.test.js.map +1 -1
  41. package/dist/skill/SKILL.md +3 -1
  42. package/dist/skill/docs/changelog.md +60 -0
  43. package/dist/skill/docs/compiler/config/index.md +14 -1
  44. package/dist/skill/docs/compiler/config/providers.md +13 -9
  45. package/dist/skill/docs/compiler/definitions/access.md +134 -2
  46. package/dist/skill/docs/compiler/definitions/actions.md +22 -0
  47. package/dist/skill/docs/compiler/definitions/changesets.md +375 -0
  48. package/dist/skill/docs/compiler/definitions/feature-areas.md +189 -0
  49. package/dist/skill/docs/compiler/definitions/feature.md +33 -0
  50. package/dist/skill/docs/compiler/definitions/firewall.md +60 -1
  51. package/dist/skill/docs/compiler/definitions/guards.md +14 -0
  52. package/dist/skill/docs/compiler/definitions/index.md +28 -3
  53. package/dist/skill/docs/compiler/definitions/masking.md +8 -0
  54. package/dist/skill/docs/compiler/definitions/read.md +13 -0
  55. package/dist/skill/docs/compiler/definitions/schema.md +36 -1
  56. package/dist/skill/docs/compiler/definitions/scopes.md +23 -1
  57. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +27 -28
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +2 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +49 -17
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +66 -0
  61. package/dist/skill/docs/stack/api-contract/index.md +136 -0
  62. package/dist/skill/docs/stack/realtime/durable-objects.md +7 -0
  63. package/dist/skill/docs/stack/realtime/index.md +22 -0
  64. package/dist/skill/docs/stack/realtime/live-views.md +56 -0
  65. package/dist/skill/docs/stack/realtime/using-realtime.md +53 -0
  66. package/dist/skill/docs/stack/webhooks/inbound.md +79 -0
  67. package/dist/skill/docs/stack/webhooks/outbound.md +33 -0
  68. package/package.json +1 -1
  69. package/src/skill/SKILL.md +3 -1
  70. package/src/skill/docs/changelog.md +60 -0
  71. package/src/skill/docs/compiler/config/index.md +14 -1
  72. package/src/skill/docs/compiler/config/providers.md +13 -9
  73. package/src/skill/docs/compiler/definitions/access.md +134 -2
  74. package/src/skill/docs/compiler/definitions/actions.md +22 -0
  75. package/src/skill/docs/compiler/definitions/changesets.md +375 -0
  76. package/src/skill/docs/compiler/definitions/feature-areas.md +189 -0
  77. package/src/skill/docs/compiler/definitions/feature.md +33 -0
  78. package/src/skill/docs/compiler/definitions/firewall.md +60 -1
  79. package/src/skill/docs/compiler/definitions/guards.md +14 -0
  80. package/src/skill/docs/compiler/definitions/index.md +28 -3
  81. package/src/skill/docs/compiler/definitions/masking.md +8 -0
  82. package/src/skill/docs/compiler/definitions/read.md +13 -0
  83. package/src/skill/docs/compiler/definitions/schema.md +36 -1
  84. package/src/skill/docs/compiler/definitions/scopes.md +23 -1
  85. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +27 -28
  86. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +2 -0
  87. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +49 -17
  88. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +66 -0
  89. package/src/skill/docs/stack/api-contract/index.md +136 -0
  90. package/src/skill/docs/stack/realtime/durable-objects.md +7 -0
  91. package/src/skill/docs/stack/realtime/index.md +22 -0
  92. package/src/skill/docs/stack/realtime/live-views.md +56 -0
  93. package/src/skill/docs/stack/realtime/using-realtime.md +53 -0
  94. package/src/skill/docs/stack/webhooks/inbound.md +79 -0
  95. package/src/skill/docs/stack/webhooks/outbound.md +33 -0
@@ -119,7 +119,7 @@ The `ctx.scope.*` arms are how **relationship-derived scopes** (attendees, shutt
119
119
 
120
120
  ## Relationship-based scoping (`via:`)
121
121
 
122
- For relationship authorization — "this user can see rows X if they have a confirmed `event_guests` row pointing at X" — declare the relationship under `authz.relationships` in `quickback.config.ts`, then reference it from `firewall:` with a `via:` predicate:
122
+ For relationship authorization — "this user can see rows X if they have a confirmed `event_guests` row pointing at X" — declare the relationship under `authz.relationships` in `quickback.config.ts`, then reference it from `firewall:` with a `via:` predicate. These relationships (and the named roles/permissions built on them) are defined once, centrally — see [Centrally defined access rules](/compiler/definitions/access#centrally-defined-access-rules).
123
123
 
124
124
  ```typescript
125
125
  // quickback.config.ts
@@ -212,6 +212,65 @@ The compile-time analyzer additionally flags a referenced permission that can
212
212
  never be satisfied, an arm shadowed by a broader one, and the SQL / CTE cost
213
213
  of each permission — see [Diagnostics](/compiler/definitions/diagnostics).
214
214
 
215
+ ## Named tenant anchors (`{ tenant }`)
216
+
217
+ The tenant predicate `{ field: 'organizationId', equals: 'ctx.activeOrgId' }` tends to be repeated on every table. Declare it **once** as a named anchor and reference it by name:
218
+
219
+ ```typescript
220
+ // quickback.config.ts
221
+ authz: {
222
+ tenants: {
223
+ org: { column: 'organizationId', equals: 'ctx.activeOrgId' },
224
+ },
225
+ }
226
+
227
+ // any firewall — top level or inside all/any groups:
228
+ firewall: [
229
+ { tenant: 'org' }, // → { field: 'organizationId', equals: 'ctx.activeOrgId' }
230
+ { field: 'deletedAt', isNull: true },
231
+ ]
232
+
233
+ // per-site COLUMN override (the claim side is never overridable):
234
+ firewall: [{ field: 'orgId', tenant: 'org' }]
235
+ ```
236
+
237
+ The anchor's `equals` must be a **verified ctx claim**: `ctx.activeOrgId` | `ctx.userId` | `ctx.scope.<kind>` | `ctx.scope.<kind>.<subKey>`. `ctx.activeTeamId` (drop-when-absent semantics stay a per-resource decision) and legacy aliases are rejected at declaration time — an anchor can never bind a request-derived value. A `{ tenant }` reference carrying its own `equals` is a compile error (one source of truth); an unknown anchor name is a compile error listing the declared anchors.
238
+
239
+ Expansion happens at compile time, before rendering — the emitted SQL is byte-identical to writing the predicate inline. Auth-DB read views accept the same anchors as a string: [`tenant: 'org'`](/stack/realtime/live-views#auth-db-includes-source-auth) — with one extra constraint: an anchor referenced from an auth-view include must bind a single-segment session claim (`ctx.<claim>`); scope-principal claims (`ctx.scope.*`) are firewall-lane bindings and are rejected there.
240
+
241
+ ## Named gate references (`{ rule }`)
242
+
243
+ A [gate](/compiler/definitions/access#named-gates-authzrules) that declares `firewall` lanes can be stamped onto a resource by name:
244
+
245
+ ```typescript
246
+ // quickback.config.ts
247
+ authz: {
248
+ rules: {
249
+ eventRow: {
250
+ who: { roles: ['owner', 'admin', 'member'] },
251
+ firewall: [{ any: [
252
+ { tenant: 'org' }, // org staff
253
+ { field: 'eventId', equals: 'ctx.scope.event' }, // signed scope claim
254
+ ] }],
255
+ },
256
+ },
257
+ }
258
+
259
+ // the resource:
260
+ firewall: [{ rule: 'eventRow' }]
261
+ // composes with the resource's own lanes (top-level AND):
262
+ firewall: [{ rule: 'eventRow' }, { field: 'kind', equals: 'ctx.scope.event.kind' }]
263
+ ```
264
+
265
+ Semantics — **AND-compose, top-level only, a reference can only narrow**:
266
+
267
+ - The gate's lanes splice into the resource's **top-level AND array** in place. They never replace the resource's own lanes, and composition can only *narrow* the row set.
268
+ - `{ rule }` is **not** valid inside an `{ all }` / `{ any }` group — a gate's firewall is one-or-more AND lanes, and splicing a multi-lane gate into an `any` group would OR-flatten it, admitting rows in **other tenants** that merely match one lane. This is a type error at authoring time and a compile error at coerce time.
269
+ - A gate's firewall may not contain `{ exception: true }` (a named bundle can never smuggle a firewall opt-out) or another `{ rule }` (gates don't nest — expansion is single-step, so cycles are impossible by construction).
270
+ - A gate with **no** `firewall` arm referenced from `firewall:` is a compile error — a who/record-only gate would silently contribute zero row lanes while the `record:` filter only ever applies at access sites.
271
+
272
+ The splice expands before validation and rendering, so the emitted `buildFirewallConditions` helper is byte-identical to writing the lanes inline — same groups, same absent-claim `1 = 0` guards, same `via:` subqueries.
273
+
215
274
  ## Context Sources
216
275
 
217
276
  When `equals` references the request context, use these standard sources:
@@ -111,6 +111,20 @@ firewall: [
111
111
 
112
112
  The semantic rule is "if the firewall says this column's value comes from the request context, the client cannot submit it." The value is auto-populated on create / upsert from `ctx`.
113
113
 
114
+ ### Changeset ops widen the set per-surface
115
+
116
+ On [changeset](/compiler/definitions/changesets) ops, an owned child's
117
+ systemManaged set additionally includes its **spine FK and every `inherit`
118
+ column** — the changeset supplies those structurally (the FK from the parent
119
+ op's id, inherit columns from the firewall-verified parent row), so a
120
+ client-supplied value is a pointer-carrying `GUARD_SYSTEM_MANAGED` rejection
121
+ (never silently stripped or stamped-over).
122
+
123
+ The child's **plain-CRUD guards are unaffected**: a junction that keeps its FK
124
+ in `createable` for its raw `POST` route stays correct — the same field
125
+ arriving in a changeset op is rejected because that surface stamps it. Two
126
+ surfaces, one declared rule each.
127
+
114
128
  ## Example
115
129
 
116
130
  ```typescript
@@ -23,13 +23,38 @@ my-app/
23
23
  │ ├── candidates.ts # Table + config (defineTable)
24
24
  │ ├── applications.ts # Secondary table + config
25
25
  │ ├── interview-scores.ts # Internal table (no routes)
26
- │ ├── actions.ts # Custom actions (optional)
27
- │ └── handlers/ # Action handlers (optional)
28
- │ └── advance-stage.ts
26
+ │ ├── actions/ # Custom actions — one file per action
27
+ │ │ └── advance-stage.ts
28
+ │ ├── lib/ # Feature-local helpers (optional)
29
+ │ └── pages/ # CMS page definitions (optional)
29
30
  ├── src/ # Generated code (output)
30
31
  └── package.json
31
32
  ```
32
33
 
34
+ `actions/`, `handlers/`, `lib/`, and `pages/` are the **reserved** sub-directories of a
35
+ feature — nothing else inside a feature folder is loaded, and a stray subdirectory that
36
+ contains `defineTable(...)` / `defineAction(...)` files fails the compile (files silently
37
+ disappearing after a mis-move is the failure mode this guards against).
38
+
39
+ Features can also be grouped into **areas**: a folder carrying an `_area.ts`
40
+ (`export default defineArea({...})`) declares a route prefix + admission gate and a shared
41
+ authz vocabulary, and every unreserved child directory becomes a child feature (nesting to
42
+ arbitrary depth):
43
+
44
+ ```
45
+ quickback/features/
46
+ ├── workspace/ # AREA (has _area.ts)
47
+ │ ├── _area.ts # defineArea({...}) — prefix, via lanes, vocabulary
48
+ │ ├── projects.ts # the area folder may itself be a feature
49
+ │ └── tasks/ # child feature
50
+ │ ├── tasks.ts
51
+ │ └── actions/addTask.ts
52
+ └── billing/ # flat feature (unchanged)
53
+ ```
54
+
55
+ Area projects must declare `requires: ['feature-areas']` in `quickback.config.ts`.
56
+ See [Feature areas](/compiler/definitions/feature-areas) for the full model.
57
+
33
58
  **Table files** use `defineTable` to combine schema and security config:
34
59
 
35
60
  ```typescript
@@ -145,6 +145,14 @@ The `'owner'` condition compares against the owner column declared via `q.scope(
145
145
 
146
146
  Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }`) are **not yet supported in `show:` clauses**. The compiler refuses to build with a clear error message because async, db-aware mask functions plus a batched relationship matcher (to avoid N+1 on list responses) are required to ship safely — that pipeline has not yet landed. The runtime evaluator fails closed on unrecognized arms, so silent grants are impossible.
147
147
 
148
+ ### Named gates in masking
149
+
150
+ [Named gates](/compiler/definitions/access#named-gates-authzrules) (`authz.rules`) follow the same discipline in `show:`:
151
+
152
+ - A **who-only** gate expands like a named role (its flat role list; the owner-gated flat-role constraint above applies).
153
+ - A gate carrying a **`record:`** predicate is a **compile error** — masking cannot evaluate record conditions, so the record dimension would be silently dropped.
154
+ - A gate carrying **firewall lanes** is a **compile error** — masking has no firewall array to satisfy, so the gate's row lanes would silently not apply. Reference a who-only rule (or inline the roles) in `show:`, and stamp the firewall gate on the resource's `firewall:` instead.
155
+
148
156
  **Workarounds**, depending on intent:
149
157
 
150
158
  - **Gate on BA roles only**: keep masking simple and put the relationship check at the access layer instead — `read.views.<v>.access: { roles: ['guest'] }` returns a curated field projection that excludes the sensitive column entirely for non-staff callers, without involving masking.
@@ -53,6 +53,8 @@ export default defineTable(customers, {
53
53
  | `GET /api/v1/{resource}/:id` | `read.access` |
54
54
  | `GET /api/v1/{resource}/views/{name}` | `read.views[name].access` (falls back to `read.access`) |
55
55
 
56
+ Each `access` block takes a `roles: [...]` array. When the same role expression recurs across reads/views/CRUD, define it once in `authz.roles` and reference it by name — see [Centrally defined access rules](/compiler/definitions/access#centrally-defined-access-rules).
57
+
56
58
  Single-record `GET /:id` inherits `read.access` automatically — there's no
57
59
  separate `read.get` block. If you need different access for single records,
58
60
  use record-level conditions on `read.access`:
@@ -208,9 +210,20 @@ export default defineTable(balanceSnapshots, {
208
210
  });
209
211
  ```
210
212
 
213
+ ## Aggregate Reads
214
+
215
+ Reading a parent **with** its owned relations is served today by `defineView`
216
+ includes (reverse-FK embedding with per-included-table firewall + masking) and
217
+ contract-v2 `?include=` on FK columns. The aggregate-changeset write surface
218
+ ([changesets](/compiler/definitions/changesets)) deliberately returns the
219
+ **root row only** in v1 — a nested aggregate representation is the phase-2
220
+ reader and will land on `?include=` over the `owns` graph, not on the write
221
+ response.
222
+
211
223
  ## See Also
212
224
 
213
225
  - [Views](/compiler/definitions/views) — Full reference for named projections
226
+ - [Changesets](/compiler/definitions/changesets) — Atomic writes over the `owns` graph
214
227
  - [Access](/compiler/definitions/access) — Roles, record conditions, and combinators
215
228
  - [Firewall](/compiler/definitions/firewall) — Tenant scoping and `firewallErrorMode`
216
229
  - [Views API](/compiler/targets/hono-api/using-the-api/views-api) — Calling views from clients
@@ -78,7 +78,7 @@ A few mechanics to know:
78
78
  - **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
79
79
  - **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
80
80
  - **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
81
- - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`.
81
+ - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/compiler/definitions/changesets) on the root to generate the atomic aggregate write path.
82
82
  - **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
83
83
 
84
84
  ### Column Types
@@ -95,6 +95,7 @@ A few mechanics to know:
95
95
  | `q.enum(['a','b'])` | `text(..., { enum: [...] })` | `z.enum([...])` |
96
96
  | `q.id()` | `text('id').primaryKey()` | `z.string()` |
97
97
  | `q.scope(kind)` | `text(...).notNull()` | `z.string()` |
98
+ | `q.stamp({ fromScope, claim })` | `text(...).notNull()` (nullable with `optional: true`) | `z.string().optional()` |
98
99
 
99
100
  `q.text()` and `q.url()` accept either a SQL-name string or an options object — `q.text({ sqlName: 'org_id', maxLength: 80 })`. `maxLength` adds `z.string().max(n)` at the validation edge; the SQL column stays `text` (D1 ignores `VARCHAR(n)` length anyway).
100
101
 
@@ -132,6 +133,38 @@ ownerId: q.scope('owner', { source: 'ctx.userId' }),
132
133
 
133
134
  `q.scope()` is preferred over `q.text().required()` for tenant columns. Auto-detection on column names (`organizationId`, `userId`, etc.) still works as a fallback for projects bringing forward Drizzle schemas, but the explicit `q.scope()` form locks in the semantics in the source.
134
135
 
136
+ ### q.stamp() — proven-principal identity columns
137
+
138
+ `q.stamp({ fromScope, claim })` server-stamps a column from a **proven** scope claim — the caller's own identity within a relationship they were cryptographically proven to hold (e.g. an event attendee's own guest id). It is the identity sibling of `q.scope`:
139
+
140
+ | | `q.scope('<kind>')` | `q.stamp({ fromScope, claim })` |
141
+ |---|---|---|
142
+ | **Purpose** | tenant isolation column | proven-principal **identity** column |
143
+ | **Value** | `ctx.scope.<kind>.id` / `activeOrgId` / `userId` | `ctx.scope.<kind>.<claim>` (`id` \| `subjectId` \| a scalar sub-key) |
144
+ | **Firewall arm?** | **yes** — it is the tenant `WHERE` | **never** — identity is not a tenant scope |
145
+ | **Guarantee** | "stamp **and verify**" (firewall re-checks on read/patch/delete) | "stamp **and prove**" (un-spoofable by token provenance) |
146
+
147
+ ```typescript
148
+ columns: {
149
+ eventId: q.scope('event'), // tenant firewall column
150
+ authorId: q.stamp({ fromScope: 'event', claim: 'subjectId' }), // proven identity — un-spoofable
151
+ }
152
+ ```
153
+
154
+ **Runtime precedence — the org/admin hierarchy takes priority.** The stamp fires **only when the caller is admitted as a scope-only principal** (a scope-token holder, `ctx.scopePrincipal === true`): the column is force-stamped from the proven claim and any client-sent value is ignored. A caller admitted via the **org role hierarchy** (member / admin / owner) writes the column through the **org path** — a normal client-settable value, bounded by the org firewall (this is legitimate org-admin capability over their own org's rows). So a table whose `create` admits *both* org roles and a scope role needs **no split**: each identity writes the column the way its principal allows. The invariant that always holds is that a scope-only principal can never set a scope-stamped column to anything but its proven token.
155
+
156
+ **Fail-closed.** If a scope-only caller reaches the write without the required claim (`ctx.scope.<kind>.<claim>` absent) the write is refused with **403** *before* the insert — never a `NULL` identity row — for nullable stamp columns too. A `q.stamp` column may not also be a firewall arm, live on an `exception: true` table, or be sourced from a set-valued sub-key; each is a compile error.
157
+
158
+ `optional: true` makes the DDL column nullable (an org caller may then omit it); it does **not** relax the scope-principal 403.
159
+
160
+ **Set-on-insert, immutable thereafter.** A `q.stamp` column is a **create-time identity** — it is never re-derived on update. On every update-shaped write (`PATCH`, `PUT`, batch update, upsert, and a changeset root/child patch) the column is **systemManaged**: a client value for it is **rejected** (400), regardless of your `guards.updatable` list. Re-keying a proven identity is not an operation. (The force-stamp and the org-writable-on-create allowance apply to the create path only.)
161
+
162
+ **A non-nullable stamp on the org path must be supplied by the caller.** The force-stamp fires for scope-only principals; an org-admitted caller writes the column as normal client input. So a `NOT NULL` `q.stamp` column (the default) that an org caller *omits* lands on the database `NOT NULL` constraint (a deterministic field-named 400), not a NULL row. Add the column to `guards.createable` so org callers can supply it, or mark it `optional: true` if an org-created row may legitimately have no identity.
163
+
164
+ **The scope-only lane needs a scope-reachable write.** The force-stamp only runs once the scope-only principal actually *reaches* the insert. A table with a **hard organization firewall arm** (an `organizationId` sourced from `ctx.activeOrgId`) emits an `ORG_REQUIRED` gate that denies a sessionless scope principal (who has no active org) *before* the stamp — so on such tables the stamp serves the **org-admitted** caller, and the scope-only principal writes these rows as a **changeset child** that *inherits* `organizationId` from a firewall-verified parent. For a plain create/batch by a scope-only principal, firewall the table on the **scope** arm only (e.g. `firewall: { any: [{ field: 'eventId', equals: 'ctx.scope.event' }] }`, no org column) so no `ORG_REQUIRED` gate is emitted.
165
+
166
+ **Idempotency (at-least-once).** The stamp rides inside the write, so it inherits the endpoint's replay semantics: a **keyed** replay (a repeated `Idempotency-Key` whose handler is skipped) neither re-writes nor re-stamps; a **keyless** retry re-writes and therefore re-stamps from the caller's then-current proven claim.
167
+
135
168
  ### Naming Convention
136
169
 
137
170
  By default, `q` picks the SQL column name from the JS key using the target database's conventional casing. Both `cloudflare-d1` and `neon` default to **`snake_case`** (`organizationId` → `organization_id`).
@@ -490,6 +523,8 @@ ownerId: text('owner_id').notNull()
490
523
  teamId: text('team_id').notNull()
491
524
  ```
492
525
 
526
+ Those three are **tenant** auto-stamps (org / owner / team). To auto-stamp a **proven-principal identity** column instead — the caller's own id within a relationship, not a tenant key — use [`q.stamp()`](#qstamp--proven-principal-identity-columns). It sources from `ctx.scope.<kind>.<claim>` for scope-only principals and, unlike the tenant stamps, is never a firewall arm.
527
+
493
528
  ## Display Column
494
529
 
495
530
  When a table has foreign key columns (e.g., `departmentId` referencing `departments`), Quickback can automatically resolve the human-readable label in GET and LIST responses. This eliminates the need for frontend lookup calls.
@@ -21,7 +21,12 @@ Most scope principals are signed-in users who prove a relationship at [`/scope/v
21
21
 
22
22
  ### 1. Declare relationships + scopes
23
23
 
24
- A scope **kind** (`event`) declares named **roles**, each conferred by a relationship whose `from` row carries the role (and optionally a **sub-key** for row slicing):
24
+ A scope **kind** (`event`) declares named **roles**, each conferred by a relationship whose `from` row carries the role (and optionally a **sub-key** for row slicing).
25
+
26
+ Scope kinds declare at root `authz` (visible everywhere) or inside a
27
+ [feature area](/compiler/definitions/feature-areas)'s `_area.ts` — then the kind, its bare
28
+ role aliases, the canonical `scope:<kind>:<role>` spellings, and `ctx.scope.<kind>` accessors
29
+ are all visible to that area's subtree only (any outside reference is a compile error):
25
30
 
26
31
  ```typescript
27
32
  // quickback.config.ts
@@ -173,6 +178,23 @@ kinds map to their session fields (`organization` → `ctx.activeOrgId`,
173
178
  `owner` → `ctx.userId`, `team` → `ctx.activeTeamId`); any other kind maps to
174
179
  `ctx.scope.<kind>.id`.
175
180
 
181
+ ### Stamping a proven *identity* claim (`q.stamp`)
182
+
183
+ `q.scope('event')` stamps the **tenant** id (`ctx.scope.event.id`). To stamp a
184
+ different **proven claim** off the same verified scope — the caller's own
185
+ `subjectId` (the conferring row's PK) or a scalar sub-key — use
186
+ [`q.stamp`](/compiler/definitions/schema#qstamp--proven-principal-identity-columns):
187
+
188
+ ```typescript
189
+ authorId: q.stamp({ fromScope: 'event', claim: 'subjectId' }),
190
+ ```
191
+
192
+ Every proven scope carries `id`, `subjectId`, and any projected sub-keys; a
193
+ `q.stamp` column reads one of those. Unlike `q.scope` it is **never** a firewall
194
+ arm (identity is not a tenant scope), and it force-stamps **only** for scope-only
195
+ principals — an org member/admin/owner writes it via the org path. A scope-only
196
+ caller missing the claim gets a fail-closed **403**, never a `NULL` row.
197
+
176
198
  ## Namespace scope-claim refresh
177
199
 
178
200
  A scope is normally minted at `POST /scope/v1/enter`. When you also mount a
@@ -286,34 +286,33 @@ on staging or production targets. Wrangler uses this field only for local
286
286
  development; deployed Workers obtain their
287
287
  connection string from the Hyperdrive configuration identified by `id`.
288
288
 
289
- <Callout>
290
- The generated setup uses three Postgres roles: `quickback_owner` (NOLOGIN object
291
- owner for the app/auth schemas), `quickback_admin` (migration/setup actor — use
292
- its unpooled URL for `DATABASE_MIGRATION_URL`), and `quickback` (the Worker
293
- runtime role, the **only** deployed DB role — use its pooled URL for
294
- `DATABASE_URL`). The first generated migration bootstraps these roles as
295
- NOLOGIN; enable login and set passwords before use. Full walkthrough in the
296
- generated `docs/neon-setup.md`.
297
-
298
- Run the **first** `db:migrate` with your database owner credential (Neon's
299
- `neondb_owner`) — that bootstrap run also grants `quickback_admin` everything
300
- the Drizzle journal needs (`CREATE` on the database, plus ownership of the
301
- `drizzle` schema and `drizzle.__drizzle_migrations`). Routine migrates **after**
302
- bootstrap — applying new schema deltas — then run entirely as `quickback_admin`
303
- via `DATABASE_MIGRATION_URL`, no owner credential required. This includes the
304
- pinned runner's `CREATE SCHEMA IF NOT EXISTS drizzle` preamble, which needs
305
- database-level `CREATE` even as a no-op and previously forced every migrate
306
- back onto the owner credential. (A change to the **security/RLS config** appends
307
- a new `quickback_rls` migration that re-runs the role bootstrap, so re-point
308
- `DATABASE_MIGRATION_URL` at the owner credential for that one apply.)
309
-
310
- Each security migration first removes direct `PUBLIC` and `quickback` runtime
311
- privileges from the Drizzle schema, journal table, journal sequences, and
312
- database-level `CREATE`, then restores the migration role's capability. The
313
- audit schema/table likewise revoke prior direct grants before restoring only
314
- runtime schema usage + table `INSERT` and admin forensic access. Reapplying a
315
- migration therefore converges privilege drift instead of merely adding grants.
316
- </Callout>
289
+ > The generated setup uses three Postgres roles: `quickback_owner` (NOLOGIN object
290
+ > owner for the app/auth schemas), `quickback_admin` (migration/setup actor — use
291
+ > its unpooled URL for `DATABASE_MIGRATION_URL`), and `quickback` (the Worker
292
+ > runtime role, the **only** deployed DB role — use its pooled URL for
293
+ > `DATABASE_URL`). The first generated migration bootstraps these roles as
294
+ > NOLOGIN; enable login and set passwords before use. Full walkthrough in the
295
+ > generated `docs/neon-setup.md`.
296
+ >
297
+ > Run the **first** `db:migrate` with your database owner credential (Neon's
298
+ > `neondb_owner`) — that bootstrap run also grants `quickback_admin` everything
299
+ > the Drizzle journal needs (`CREATE` on the database, plus ownership of the
300
+ > `drizzle` schema and `drizzle.__drizzle_migrations`). Routine migrates **after**
301
+ > bootstrap — applying new schema deltas — then run entirely as `quickback_admin`
302
+ > via `DATABASE_MIGRATION_URL`, no owner credential required. This includes the
303
+ > pinned runner's `CREATE SCHEMA IF NOT EXISTS drizzle` preamble, which needs
304
+ > database-level `CREATE` even as a no-op and previously forced every migrate
305
+ > back onto the owner credential. (A change to the **security/RLS config** appends
306
+ > a new `quickback_rls` migration that re-runs the role bootstrap, so re-point
307
+ > `DATABASE_MIGRATION_URL` at the owner credential for that one apply.)
308
+ >
309
+ > Each security migration first removes direct `PUBLIC` and `quickback` runtime
310
+ > privileges from the Drizzle schema, journal table, journal sequences, and
311
+ > database-level `CREATE`, then restores the migration role's capability. The
312
+ > audit schema/table likewise revoke prior direct grants before restoring only
313
+ > runtime schema usage + table `INSERT` and admin forensic access. Reapplying a
314
+ > migration therefore converges privilege drift instead of merely adding grants.
315
+
317
316
 
318
317
  ## Better Auth schema generation
319
318
 
@@ -277,6 +277,8 @@ fail-fast per-record loop, `meta.transactional: false`.
277
277
  | `PUT /batch` (upsert) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
278
278
  | `POST /batch` (create) | (any) | (any) | `true` | Single bulk `INSERT` — atomic at the DB level. |
279
279
  | `DELETE /batch` | (any) | (any) | `true` | Single bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. |
280
+ | [Changeset](/compiler/definitions/changesets) (`application/vnd.quickback.changeset+json`, contract v2) | tx-supporting (postgres, neon over websocket/hyperdrive) | n/a | `true` | Root op + every child op share one transaction; any op failure rolls back the whole changeset. |
281
+ | [Changeset](/compiler/definitions/changesets) | cloudflare-d1, neon over http (Cloudflare default) | n/a | `false` | Deterministic parent-first fail-fast — the first op failure stops the changeset; already-applied ops stay committed (a consistent, independently-authorized prefix). |
280
282
 
281
283
  ### Reading `meta.transactional` in clients
282
284
 
@@ -13,15 +13,32 @@ The generated API returns structured error responses with consistent fields acro
13
13
  | `401` | Unauthorized | Missing or expired authentication |
14
14
  | `403` | Forbidden | Access denied (wrong role, condition failed) or firewall blocked it |
15
15
  | `404` | Not Found | Record doesn't exist (or firewall blocked with `errorMode: 'hide'`) |
16
+ | `409` | Conflict | Unique constraint hit, or a duplicate [`Idempotency-Key`](/stack/api-contract#idempotency-key) still in flight |
17
+ | `412` | Precondition Failed | [Changeset](/compiler/definitions/changesets) `If-Match` revision mismatch |
18
+ | `422` | Unprocessable | `Idempotency-Key` reused with a different request or principal |
19
+ | `428` | Precondition Required | `If-Match` sent where no revision exists (root without `updatedAt`, or the POST changeset variant) |
16
20
  | `429` | Too Many Requests | Rate limit exceeded |
21
+ | `500` | Internal Error | Uncaught throw — generic body, full error server-side |
17
22
 
18
- ## Error Response Format
23
+ ## Error Response Format — RFC 9457 Problem Details
19
24
 
20
- All errors use a flat structure with contextual fields. Every structured error response also carries a `request` block with the HTTP method, URL, request ID, and a redacted+truncated copy of the request body — enough to triage or hand the response to an LLM agent without grepping logs:
25
+ Every top-level error response is an
26
+ [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details document,
27
+ served as `application/problem+json` (see
28
+ [API Contract](/stack/api-contract)).
29
+ Quickback's contextual fields (`code`, `layer`, `details`, `hint`, `request`)
30
+ survive as 9457 **extension members**, so clients that switch on `code` keep
31
+ working. Every structured error also carries a `request` block with the HTTP
32
+ method, URL, request ID, and a redacted+truncated copy of the request body —
33
+ enough to triage or hand the response to an LLM agent without grepping logs:
21
34
 
22
35
  ```json
23
36
  {
24
- "error": "Insufficient permissions",
37
+ "type": "https://quickback.dev/problems/access-role-required",
38
+ "title": "Access role required",
39
+ "status": 403,
40
+ "detail": "Insufficient permissions",
41
+ "instance": "/api/v1/candidates/cnd_01H.../advance",
25
42
  "layer": "access",
26
43
  "code": "ACCESS_ROLE_REQUIRED",
27
44
  "details": {
@@ -40,12 +57,21 @@ All errors use a flat structure with contextual fields. Every structured error r
40
57
 
41
58
  | Field | Type | Description |
42
59
  |-------|------|-------------|
43
- | `error` | string | Human-readable error message |
44
- | `layer` | string | Security layer that rejected the request |
45
- | `code` | string | Machine-readable error code |
46
- | `details` | object | Layer-specific context (optional) |
47
- | `hint` | string | Actionable guidance for resolution (optional) |
48
- | `request` | object | Method, URL, redacted body, and request ID. Auto-attached by the runtime so the error body is self-contained — bodies are capped at 4 KB and well-known sensitive keys (`password`, `token`, `secret`, `apiKey`, `otp`, `code`, `authorization`, …) are replaced with `"[REDACTED]"` |
60
+ | `type` | string | Problem type URI — `https://quickback.dev/problems/<code-in-kebab-case>` |
61
+ | `title` | string | Human-stable summary derived from the code |
62
+ | `status` | number | The HTTP status, repeated in the body |
63
+ | `detail` | string | Human-readable error message (optional) |
64
+ | `instance` | string | Request path (optional) |
65
+ | `layer` | string | Extension — security layer that rejected the request |
66
+ | `code` | string | Extension — machine-readable error code (the full enum ships in `openapi.json` as `Problem.code`) |
67
+ | `details` | object | Extension — layer-specific context (optional) |
68
+ | `pointer` | string | Extension — first offending field for validation failures, e.g. `/stage` (optional) |
69
+ | `hint` | string | Extension — actionable guidance for resolution (optional) |
70
+ | `request` | object | Extension — method, URL, redacted body, and request ID. Auto-attached by the runtime so the error body is self-contained — bodies are capped at 4 KB and well-known sensitive keys (`password`, `token`, `secret`, `apiKey`, `otp`, `code`, `authorization`, …) are replaced with `"[REDACTED]"` |
71
+
72
+ The per-layer examples below are abbreviated to `detail` plus each layer's
73
+ extension members — every real response also carries `type`, `title`,
74
+ `status`, and (where derivable) `instance`.
49
75
 
50
76
  ## Errors by Security Layer
51
77
 
@@ -55,7 +81,7 @@ Missing or invalid authentication tokens.
55
81
 
56
82
  ```json
57
83
  {
58
- "error": "Authentication required",
84
+ "detail": "Authentication required",
59
85
  "layer": "authentication",
60
86
  "code": "AUTH_MISSING",
61
87
  "hint": "Include Authorization header with Bearer token"
@@ -78,7 +104,7 @@ Records outside the user's firewall scope return **403 Forbidden** by default wi
78
104
 
79
105
  ```json
80
106
  {
81
- "error": "Record not found or not accessible",
107
+ "detail": "Record not found or not accessible",
82
108
  "layer": "firewall",
83
109
  "code": "FIREWALL_NOT_FOUND",
84
110
  "hint": "Check the record ID and your organization membership"
@@ -104,7 +130,7 @@ Access violations return **403 Forbidden** when the user's role doesn't match th
104
130
 
105
131
  ```json
106
132
  {
107
- "error": "Insufficient permissions",
133
+ "detail": "Insufficient permissions",
108
134
  "layer": "access",
109
135
  "code": "ACCESS_ROLE_REQUIRED",
110
136
  "details": {
@@ -130,12 +156,13 @@ Guard violations return **400 Bad Request** when the request body contains field
130
156
 
131
157
  ```json
132
158
  {
133
- "error": "Field cannot be set during creation",
159
+ "detail": "Field cannot be set during creation",
134
160
  "layer": "guards",
135
161
  "code": "GUARD_FIELD_NOT_CREATEABLE",
136
162
  "details": {
137
163
  "fields": ["stage"]
138
164
  },
165
+ "pointer": "/stage",
139
166
  "hint": "These fields are set automatically or must be omitted"
140
167
  }
141
168
  ```
@@ -160,7 +187,7 @@ Surfaced when a SQL write fails *post-validation* — most often a `NOT NULL` or
160
187
 
161
188
  ```json
162
189
  {
163
- "error": "Duplicate value",
190
+ "detail": "Duplicate value",
164
191
  "layer": "database",
165
192
  "code": "DB_UNIQUE_VIOLATION",
166
193
  "details": { "column": "email" },
@@ -188,6 +215,11 @@ Batch operations can return:
188
215
 
189
216
  ### Partial Success (207)
190
217
 
218
+ A 207 body is a **success envelope** (plain `application/json`, not
219
+ `application/problem+json`) — the per-record `error` objects embedded in it
220
+ keep the internal flat shape (`error` message field, `layer`, `code`,
221
+ `details`, `hint`):
222
+
191
223
  ```json
192
224
  {
193
225
  "success": [{ "id": "app_1", "candidateId": "cand_101", "stage": "applied" }],
@@ -212,7 +244,7 @@ Batch operations can return:
212
244
 
213
245
  ```json
214
246
  {
215
- "error": "Batch operation failed in atomic mode",
247
+ "detail": "Batch operation failed in atomic mode",
216
248
  "layer": "validation",
217
249
  "code": "BATCH_ATOMIC_FAILED",
218
250
  "details": {
@@ -243,7 +275,7 @@ cause, or stack frames. The raw error is always logged server-side.
243
275
 
244
276
  ```json
245
277
  {
246
- "error": "Action execution failed",
278
+ "detail": "Action execution failed",
247
279
  "layer": "action",
248
280
  "code": "ACTION_EXECUTION_FAILED",
249
281
  "details": {
@@ -269,7 +301,7 @@ the response → log correlation is one grep.
269
301
 
270
302
  ```json
271
303
  {
272
- "error": "Internal error",
304
+ "detail": "Internal error",
273
305
  "layer": "database",
274
306
  "code": "INTERNAL_ERROR",
275
307
  "details": { "operation": "request handling" },
@@ -195,3 +195,69 @@ This request:
195
195
  | `search` | LIST, VIEW | Search text across all text columns |
196
196
  | `field=value` | LIST, VIEW | Filter by exact match |
197
197
  | `field.op=value` | LIST, VIEW | Filter with operator (gt, gte, lt, lte, ne, like, in) |
198
+ | `starting_after` | LIST, VIEW | Opaque keyset cursor — rows strictly after the boundary |
199
+ | `ending_before` | LIST, VIEW | Opaque keyset cursor — rows strictly before the boundary |
200
+ | `include` | LIST, VIEW, GET | FK-graph embedding (contract v2, allowlisted — see below) |
201
+ | `fields[<fk>]` | LIST, VIEW, GET | Sparse fields for an embedded include target (contract v2) |
202
+
203
+ ## Include & Sparse Fields (contract v2)
204
+
205
+ On the v2 contract a resource can allowlist FK columns for **FK-graph
206
+ embedding**, collapsing client-side N+1 fetches:
207
+
208
+ ```ts title="quickback/features/orders/order-items.ts"
209
+ export default feature("orderItems", {
210
+ columns: {
211
+ id: q.id(),
212
+ orderId: q.text().required().references(() => orders.id),
213
+ organizationId: q.scope("organization"),
214
+ },
215
+ read: {
216
+ access: { roles: ["member", "admin"] },
217
+ include: ["orderId"], // FK columns eligible for ?include=
218
+ },
219
+ });
220
+ ```
221
+
222
+ ```bash
223
+ GET /api/v2/order-items?include=orderId&fields[orderId]=id,total
224
+ ```
225
+
226
+ ```json
227
+ {
228
+ "data": [ { "id": "oi_1", "orderId": "ord_9" } ],
229
+ "included": { "orderId": { "ord_9": { "id": "ord_9", "total": 129 } } }
230
+ }
231
+ ```
232
+
233
+ Embedded rows land in a **top-level `included` map** keyed by FK column, then
234
+ by target primary key — row objects are never mutated.
235
+
236
+ **Security semantics (all enforced, fail-closed):**
237
+
238
+ - An embedded read **is a read of the target resource**: the target's own
239
+ `read.access` is checked before any fetch (403 on failure, never silent
240
+ omission), the child query runs under the target's tenant firewall on the
241
+ caller's own database handle, and embedded rows pass through the target's
242
+ masking before attachment.
243
+ - Targets whose `read.access` is **record-aware** (function access, `record:`
244
+ conditions, `relationship` or `fga` arms) are refused **at compile time** —
245
+ embedding them would skip their post-fetch record checks.
246
+ - A tenant-scoped target with no resolvable firewall clause is a compile
247
+ error; a global reference table must opt out explicitly with
248
+ `firewall: { exception: true }`. Even then, the child fetch still calls
249
+ the target's own firewall helper — for a soft-deleting reference table
250
+ that helper is the soft-delete predicate, so an embed never serves rows
251
+ the target's own routes refuse.
252
+ - `?include=` on a resource (or view) without an allowlist is a **400**.
253
+ Explicit views declare their own `include: [...]` — nothing is expandable
254
+ undeclared. Depth is exactly 1. A view that declares `include` must keep
255
+ each listed FK column in its `fields` projection (compile error
256
+ otherwise — the embedded lookup pivots on that column).
257
+
258
+ **Strict fields on v2:** unknown names in bare `?fields=` and in
259
+ `fields[<fk>]=` are rejected with a 400 Problem. (Pinned v1 keeps its
260
+ historical silent-drop for bare `?fields=`.) A `?fields=` projection that
261
+ drops the FK column of a requested `?include=` is also a **400** —
262
+ `include=orderId requires "orderId" in ?fields=` — never a silently-empty
263
+ `included` slot.