@quickback-dev/cli 0.54.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 +66 -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 +66 -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
@@ -0,0 +1,375 @@
1
+ # Changesets — aggregate writes
2
+
3
+ A **changeset** writes a parent row and its owned relations — junction
4
+ memberships, normalized phones/emails, line items — in **one request**,
5
+ replacing the hand-rolled multi-table action. You declare the one fact the
6
+ compiler was missing — which relations are **compositions** (owned by this
7
+ root) vs **references** (independent entities) — and the compiler generates
8
+ the whole write path.
9
+
10
+ Changesets are a **contract v2** capability (`contract: { version: "v2" }`).
11
+ Declaring `owns` on a v1-pinned project is a compile error.
12
+
13
+ ## Declaring the boundary — `owns`
14
+
15
+ ```ts title="quickback/features/projects/projects.ts"
16
+ export default feature("projects", {
17
+ // ...columns, firewall, guards, masking, read...
18
+ create: { access: { roles: ["admin", "owner"] } },
19
+ update: { access: { roles: ["admin", "owner"] } },
20
+
21
+ owns: {
22
+ tasks: {
23
+ table: "tasks", // camelCase table name — a defineTable in this project
24
+ fk: "projectId", // FK on the CHILD pointing at this root's PK
25
+ refs: { // client-supplied pointers at INDEPENDENT entities
26
+ assigneeId: "people",
27
+ reviewerId: "people", // nullable refs may be omitted or null
28
+ },
29
+ inherit: ["organizationId"], // parent columns copied onto every inserted child
30
+ owns: { // grandchildren — structural nesting, depth-capped
31
+ checklist: { table: "taskChecklistItems", fk: "taskId", inherit: ["organizationId"] },
32
+ },
33
+ },
34
+ },
35
+ });
36
+ ```
37
+
38
+ | Key | Meaning |
39
+ |---|---|
40
+ | `table` | The owned child — **must** be a `defineTable`/`feature()` in the project. String literal, never an identifier. Auth tables can never be owned. |
41
+ | `fk` | The spine: the child column pointing at this root. **Compiler-stamped** on inserts; a client-supplied value is rejected. |
42
+ | `refs` | Columns pointing at independent entities. Client-supplied, **existence-checked inside the caller's tenant** (the referenced table's firewall is ANDed) — on inserts **and** patches. The referenced row is never written through. |
43
+ | `inherit` | Tenant/denorm columns copied verbatim from the (firewall-verified) parent row onto every inserted child. Compiler-stamped; client values rejected. |
44
+ | `owns` | Nested owned relations. Max 3 levels of nesting (the aggregate spans at most 4 tables). |
45
+
46
+ A child's [`q.stamp`](/compiler/definitions/schema#qstamp--proven-principal-identity-columns) identity columns are a **fourth, disjoint** source, sitting alongside `fk`/`inherit`/`refs`. On a changeset **insert** the engine stamps them from the **caller's proven scope claim** (`ctx.scope.<kind>.<claim>`) — *not* from the parent row — but only when the caller is a scope-only principal; an org-admitted caller keeps their client value (org-firewall-bounded). The contrast is exact: `inherit` copies **tenant** columns from the firewall-verified *parent*, `q.stamp` copies **identity** from the proven *token*. A required claim absent on a scope principal fails the op with **403** — emitted *before* the ref-existence checks, so a claim-less caller cannot probe which rows exist. A `refs` key may not alias a `q.stamp` column (a column is compiler-stamped **or** a client ref, never both). On a changeset **patch** op the stamp column is **immutable** — a client value for it is rejected (400) like any systemManaged column, matching the plain update path. Because the stamp lives inside the changeset handler, a **keyed** (`Idempotency-Key`) replay neither re-writes nor re-stamps; a keyless retry re-writes and re-stamps.
47
+
48
+ **Owning a relation is not a write grant.** Every changeset op is admitted by
49
+ the **child table's own crud declaration**: `insert` requires `create:` on the
50
+ child, `patch` requires `update:`, `delete` requires `delete:` (soft mode only
51
+ in v1) — each with its own `access`. There is no per-relation access override:
52
+ access is declared exactly once, on the child.
53
+
54
+ ### `routes: false` — changeset admission without a raw route
55
+
56
+ Widening a child's access for changeset use must not silently open its raw
57
+ CRUD surface. The `create`, `update`, and `delete` op configs accept
58
+ `routes: false` (`upsert`/`put` does not): the access stays declared (it is
59
+ the changeset admission gate) while the raw HTTP route — and its
60
+ auto-promoted batch variant — is never mounted, documented, or counted in
61
+ the operations manifest.
62
+
63
+ ```ts title="quickback/features/projects/tasks.ts"
64
+ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
65
+ ```
66
+
67
+ ## The wire contract
68
+
69
+ One blessed path — **RFC 5789 media-type dispatch** on the routes you already
70
+ have. No subpath.
71
+
72
+ - `PATCH /api/v2/<resource>/:id` with
73
+ `Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
74
+ to an existing root. Plain `application/json` keeps the flat-column PATCH.
75
+ - `POST /api/v2/<resource>` with the same media type — create the root and its
76
+ children in one changeset.
77
+
78
+ ```jsonc
79
+ // PATCH /api/v2/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
80
+ {
81
+ "patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
82
+ "tasks": {
83
+ "insert": [
84
+ {
85
+ "lid": "t1", // client correlation id
86
+ "title": "Ship it",
87
+ "assigneeId": "per_9", // ref — tenant-checked
88
+ "checklist": { "insert": [{ "label": "QA pass" }] } // grandchild, FKs onto t1's minted id
89
+ }
90
+ ],
91
+ "patch": [{ "id": "tsk_2", "state": "done" }],
92
+ "delete": ["tsk_3"]
93
+ }
94
+ }
95
+ ```
96
+
97
+ ```jsonc
98
+ // Response
99
+ {
100
+ "success": true,
101
+ "root": { "id": "prj_1", "name": "Renamed", /* masked through the root's masking */ },
102
+ "created": { "t1": "tsk_9a…", "/tasks/insert/0/checklist/insert/0": "tci_44…" },
103
+ "meta": { "ops": 4, "transactional": false }
104
+ }
105
+ ```
106
+
107
+ - Inserts/patches apply parent-first (document order); deletes apply
108
+ children-first.
109
+ - `lid` correlates a minted id in `created`; entries without a `lid` key on
110
+ their JSON Pointer. A nested insert's FK comes from its parent op's minted
111
+ id — an unresolvable parent lid is a pointer-carrying **400**, never a
112
+ silent re-parent onto the root.
113
+ - `Prefer: return=minimal` omits `root` from the response. v1 representation
114
+ is **root-row-only** (re-read through the root's masking) — nested aggregate
115
+ reads are the phase-2 `?include=` reader; use [`defineView`
116
+ includes](/compiler/definitions/read) today.
117
+
118
+ ### Headers
119
+
120
+ | Header | Behavior |
121
+ |---|---|
122
+ | `If-Match` | Optimistic concurrency against the **root revision** — the root's `updatedAt` (or the injected `modifiedAt` audit column). Accepted value forms: `W/"<revision>"`, `"<revision>"`, or the bare revision value, where `<revision>` is the raw value of the revision column as returned in the root row. **Do not echo `GET /:id`'s `ETag` header into `If-Match`** — that ETag is the contract layer's body-hash ETag, not this revision, and will always **412**. Compared inside the transaction; mismatch → **412**. Every accepted changeset touches the revision. A root with no revision column answers `If-Match` with **428 PRECONDITION_UNSUPPORTED** — never silently ignored; the POST variant always answers 428 (no pre-existing revision to match). |
123
+ | `Idempotency-Key` | The standard write-retry key. Claims are principal-scoped — a replayed key from a different principal is a 422, never a cached-body leak. |
124
+ | `Prefer` | `return=representation` (default) or `return=minimal`. |
125
+
126
+ ### Errors
127
+
128
+ RFC 9457 `application/problem+json`. The failing op is identified by a JSON
129
+ Pointer in the `pointer` extension (`/tasks/insert/0/assigneeId`). On
130
+ **non-transactional providers** the error also carries an `ops` extension
131
+ listing the outcomes of ops applied before the failure — the honest committed
132
+ prefix. On **transactional providers** the rollback erased every applied op,
133
+ so the error carries **no `ops` extension** (advertising rolled-back ids would
134
+ point clients at rows that no longer exist). **Outcome entries carry only
135
+ `{ pointer, status, id? }` — never child field values** (v1 deliberately
136
+ withholds nested child representation, so errors cannot become an
137
+ unmasked-child side channel).
138
+
139
+ ## The security model — "owning a relation is not a backdoor"
140
+
141
+ The **root op** runs the root table's full single-record gate stack, in order:
142
+ auth → cross-tenant guard → the root's own `update` (PATCH) / `create` (POST)
143
+ access — **always, including child-only bodies; there is no child-only bypass
144
+ lane** → firewall fetch (reveal → 403 / hide → 404, byte-consistent with the
145
+ plain handler) → `requireSelf` → root body schema + ownership guard + guards.
146
+ The POST variant runs the root's full create pipeline (org validation, FK
147
+ existence checks, defaults/computed, ownership stamping).
148
+
149
+ Every **child op** then pays:
150
+
151
+ 1. **Admission** — declared relation, declared op kind (unknown keys are 400s).
152
+ 2. **The child's own access** — the pre-record role gate runs **before any row
153
+ fetch** (no 404-vs-403 ID probing under the aggregate); `record:`
154
+ predicates are evaluated against the fetched row on patch/delete and
155
+ against the submitted input on insert.
156
+ 3. **systemManaged rejection** — client data carrying `fk`, any `inherit`
157
+ column, or an ownership column is **rejected** with the op's pointer, never
158
+ stripped or stamped-over. (The child's *plain-CRUD* guards are unaffected —
159
+ a junction may keep its FK createable for its raw route; the same field in
160
+ a changeset op is rejected because the changeset supplies it structurally.)
161
+ 4. **The child's column body schema** — q-authored children pay the same Zod
162
+ types/enums/lengths backstop their plain POST/PATCH enforces (strict,
163
+ guards-aware, with the compiler-stamped columns omitted). Drizzle-authored
164
+ children have no Zod on their plain routes either, so none applies here —
165
+ parity, not an omission.
166
+ 5. **The child's guards** — `createable`/`updatable` validation.
167
+ 6. **The child's firewall** — every patch/delete WHERE is
168
+ `spine FK = parent id AND child firewall AND id`, same-feature or
169
+ cross-feature alike. Inserts derive tenant columns only from the
170
+ firewall-verified parent row.
171
+ 7. **Tenant-scoped `refs` checks** — each non-null ref must exist inside the
172
+ referenced table's firewall, on **inserts and patches alike** (re-pointing
173
+ a ref pays the same check; only columns present in the op's data are
174
+ checked).
175
+ 8. **Server-minted child ids** — a client-supplied child primary key on an
176
+ insert is rejected (like the plain POST's strict body schema), unless the
177
+ project is configured for client-provided ids (`generateId: false`).
178
+
179
+ Child `delete` ops stamp the **fixed `deletedAt`** audit column — exactly what
180
+ the plain DELETE route stamps (the audit wrapper then auto-stamps
181
+ `deletedBy`). An `isNull` firewall arm on any other column (e.g.
182
+ `archivedAt`) is a read-scoping predicate, never the soft-delete stamp.
183
+
184
+ Compile-time, fail-closed (everything throws, nothing normalizes silently):
185
+
186
+ - **Per-arm tenant coverage**: every column arm of the child's *resolved*
187
+ firewall — including **every branch of an `any:` OR** — must be satisfiable
188
+ by `fk`/`inherit`. Covering one arm of an OR is not coverage. This runs over
189
+ the post-expansion firewall, so lanes spliced from
190
+ [`authz.rules`](/compiler/definitions/access#centrally-defined-access-rules)
191
+ gates and `{ tenant }` anchors are checked too.
192
+ - Children firewalled through a **subquery arm** (`via:`, `{ permission }`,
193
+ arrows) cannot be owned in v1 — even when the arm arrives through a gate
194
+ splice.
195
+ - `refs` keys must be **disjoint** from `{fk} ∪ inherit ∪ ownership columns` —
196
+ a column is either compiler-stamped or a client ref, never both (blocks
197
+ ownership-column injection through a ref).
198
+ - **Relationship / FGA access arms are compile errors** on the changeset lane
199
+ — on the root's `update`/`create` access and on every admitted child op's
200
+ access. Those arms are decided by inline route code the changeset engine
201
+ does not emit in v1; rather than silently widen (or silently 403) the gate,
202
+ the compiler refuses. Use roles/record predicates, or keep the write in an
203
+ authored action. (Function-form access is refused for the same reason.)
204
+ - **Envelope-encrypted roots cannot ride the changeset in v1** — the response
205
+ path does not run the decrypt-then-mask prepare helper, so the returned root
206
+ would carry sealed ciphertext. The compiler refuses rather than degrade
207
+ silently. (Sealed-mode columns are unaffected — plain routes return those
208
+ as-is too.)
209
+ - **Relation names `insert`, `patch`, `delete`, and `lid` are rejected** —
210
+ the wire parser reserves those payload keys, so such a relation would be
211
+ silently unreachable on the wire.
212
+ - One aggregate root per table, acyclic graph, bounded depth, declared child
213
+ ops only, soft-delete children only, contract v2 only.
214
+
215
+ ## `afterCommit` — emit a realtime signal after the changeset commits
216
+
217
+ A changeset that must notify live views declares **`afterCommit`** on the
218
+ aggregate root — a declarative broadcast, **not** a hand-rolled
219
+ `try { realtime.* } catch {}` tail. It fires **one aggregate-level CloudEvent**
220
+ strictly **after** the transaction commits, riding the existing
221
+ [named-invalidation / Broadcaster egress](/stack/realtime/named-invalidations)
222
+ (so it inherits the CloudEvents envelope + AsyncAPI description for free).
223
+
224
+ ```ts title="quickback/features/travel/lodging-reservations.ts"
225
+ export default defineTable(lodgingReservations, {
226
+ // ...firewall / read / crud ...
227
+ owns: { occupants: { table: "lodgingReservationGuests", fk: "reservationId",
228
+ inherit: ["eventId", "organizationId"] } },
229
+ afterCommit: {
230
+ broadcast: {
231
+ travelChanged: {
232
+ event: "attendRealtime.mobileBundleChanged.travelUpdated", // registry.event.variant
233
+ delivery: "thisEvent", // MUST be in the event's `deliveries` allowlist
234
+ payload: {
235
+ eventId: "root.eventId", // a committed root column
236
+ reservationId: "rootId", // the root pk
237
+ occupantIds: "affectedIds", // ids of child rows touched this changeset
238
+ },
239
+ },
240
+ },
241
+ },
242
+ });
243
+ ```
244
+
245
+ - **One event per aggregate**, not one per touched child. The payload carries
246
+ an **affected-ids / changed-paths** roll-up derived from the applied ops
247
+ (`affectedIds` = child ids, `changedPaths` = JSON pointers) — **ids and
248
+ pointers only, never child field values**.
249
+ - **`delivery` is required and fail-closed.** The audience lives on a named
250
+ [delivery profile](/stack/realtime/named-invalidations); it must appear in the
251
+ referenced event's `deliveries` allowlist. There is **no default selection**,
252
+ so an event permitting a narrow AND a wide room can never silently fan a
253
+ changeset frame to the wider one.
254
+ - **Payload sources:** `root.<col>` (a committed root column), `rootId`,
255
+ `affectedIds`, `changedPaths`. Every payload key the variant declares must be
256
+ mapped; unknown sources / undeclared keys are compile errors.
257
+ - **Best-effort:** a broadcast failure never rolls back the committed changeset
258
+ (`console.warn`, dispatched on `waitUntil`).
259
+ - **Root-row frame:** `afterCommit: { realtime: true }` additionally emits the
260
+ root row (postgres_changes-style) on the table's own `realtime` room. The row
261
+ rides unmasked **with the table's `MASKING_CONFIG`** so the Broadcaster masks
262
+ per-subscriber-role at fanout — the same discipline plain CRUD realtime uses.
263
+
264
+ ### Fail-closed disclosure gates
265
+
266
+ Because a broadcast payload is **not** masked at fanout (only the root-row frame
267
+ is), afterCommit fails the build rather than leak:
268
+
269
+ - A **masked `root.<col>`** may ride a broadcast only to a role-only delivery
270
+ whose roles ⊆ the column's unmask roles (same app-role namespace). A
271
+ **scope-keyed** delivery or an **empty unmask set** (`show: { or: 'owner' }`)
272
+ **always** throws.
273
+ - **`affectedIds` / `rootId` / `changedPaths`** carry firewalled row IDs
274
+ (existence/enumeration). They may ride a scope-keyed delivery (bounded to one
275
+ scope-instance room); a role-only / org-wide delivery throws unless you
276
+ acknowledge with `disclosesChildIds: true`.
277
+
278
+ ### `q.scope` verified vs `q.stamp` proven — the "stamp then emit" rule
279
+
280
+ When a changeset [stamps a proven identity](/compiler/definitions/schema#qstamp--proven-principal-identity-columns)
281
+ and then emits it, the two features compose on one write path:
282
+
283
+ | | `q.scope('<kind>')` | `q.stamp({ fromScope, claim })` |
284
+ |---|---|---|
285
+ | Purpose | tenant isolation column | proven-principal **identity** column |
286
+ | Firewall arm? | **yes** — it is the tenant WHERE | **never** |
287
+ | Verified how? | firewall re-verifies on read/patch/delete | token provenance (un-spoofable) |
288
+ | Phrase | "**stamp AND verify**" | "stamp AND **prove**" |
289
+ | Safe to broadcast? | to the matching scope-keyed room | **only** to an audience ⊆ the stamping scope kind |
290
+
291
+ A `q.stamp` identity column (e.g. `guestId`) sourced via `root.<col>` is
292
+ **audience-gated like `affectedIds`** (05×06 integration): the delivery must be
293
+ scope-keyed to the **same scope kind** that stamped it, else the build fails —
294
+ unless you acknowledge with **`disclosesStampedIdentity: true`**. A stamp is
295
+ un-spoofable, not un-*sensitive*: provenance is not audience clearance.
296
+
297
+ ### Idempotency — at-least-once
298
+
299
+ afterCommit is **at-least-once**, exactly as idempotent as the write it rides.
300
+ A retry carrying the **same `Idempotency-Key`** neither re-writes nor re-emits
301
+ (the middleware returns the cached response before the handler runs). A
302
+ **keyless** retry re-runs the whole handler → re-writes **and** re-emits. Callers
303
+ that need single-delivery must send an `Idempotency-Key`.
304
+
305
+ ### No-tx: "row written ⇏ event fired"
306
+
307
+ On a no-tx provider (D1 / neon-http), a mid-changeset failure **throws** before
308
+ the success path, so **no frames emit** for the partially-applied prefix —
309
+ `meta.transactional: false` is the only guarantee signal. A **fully-successful**
310
+ no-tx changeset **does** emit, still with `transactional: false`. Never assume
311
+ "row written ⇒ event fired"; `meta.transactional` is the contract.
312
+
313
+ > **Deferred out of v1:** embedding reindex on the changeset lane, `notify`
314
+ > (device push — a WS broadcast is not an APNs/web-push delivery), and lifting
315
+ > `afterCommit` onto plain tables/actions. The compiler still **warns** when an
316
+ > `owns` root/child declares `realtime` **without** `afterCommit`, or declares
317
+ > `embeddings`, so a silent asymmetry can't be enabled unknowingly.
318
+
319
+ ## Atomicity — honest, per provider
320
+
321
+ The whole changeset runs inside `db.transaction()` when the provider supports
322
+ it; `meta.transactional` reports the actual guarantee (same contract as
323
+ [batch operations](/compiler/targets/hono-api/using-the-api/batch-operations)):
324
+
325
+ | Provider | transactional | Behavior |
326
+ |---|---|---|
327
+ | postgres / supabase / neon (websocket / hyperdrive) / libsql / better-sqlite3 / bun-sqlite | `true` | One transaction; any op failure rolls back the root op and every child op |
328
+ | cloudflare-d1, neon over http (the Cloudflare default) | `false` | Deterministic parent-first **fail-fast**: the first failure stops the changeset; ops already applied stay committed (a consistent prefix — each was independently authorized) |
329
+
330
+ ## Calling it from authored code
331
+
332
+ The engine is exported per root as `apply<Singular>Changeset` — the seam
333
+ authored actions delegate through when they still need residue logic
334
+ (preconditions, server-side transforms, notifications) around the aggregate
335
+ write:
336
+
337
+ ```ts title="quickback/features/projects/actions/importBoard.ts"
338
+ // Action files are compiled into the feature directory, next to the
339
+ // generated module — the relative import resolves at runtime.
340
+ import { applyProjectChangeset } from "../projects.changeset";
341
+
342
+ export default defineAction({
343
+ // ...description, input, access...
344
+ execute: async ({ db, ctx, input }) => {
345
+ // precondition / transform residue …
346
+ const result = await applyProjectChangeset(db, ctx, input.projectId, input.changes);
347
+ // notify / respond …
348
+ return result;
349
+ },
350
+ });
351
+ ```
352
+
353
+ **There is no trusted mode.** The auth assertion, cross-tenant guard, and the
354
+ root's own pre-record access gate are the helper's first statements — an
355
+ authored action whose action-level access is looser than the root's crud
356
+ access still pays the root's declared authorization when it delegates. The
357
+ HTTP handler is a thin wrapper over the same helper (parse + Problem-Details
358
+ rendering only).
359
+
360
+ ## Standards mapping
361
+
362
+ | Changeset concept | Grounded in |
363
+ |---|---|
364
+ | Media-type dispatch on PATCH | RFC 5789 (the media type selects patch semantics) |
365
+ | `lid` correlation + op list | JMAP `/set` creation ids, JSON:API `lid` |
366
+ | Root-revision `If-Match` | JMAP state tokens, RFC 9110 preconditions |
367
+ | Pointer-carrying errors | RFC 9457 Problem Details + RFC 6901 JSON Pointer |
368
+ | Nested relation ops | SCIM PATCH (typed sub-resources) |
369
+
370
+ ## What stays phase 2
371
+
372
+ Full-document `replace` diff sugar (and its `key:` reconciliation field), the
373
+ `application/json-patch+json` representation, cross-branch `$lid` references,
374
+ nested `Prefer: return=representation`, `?include=` aggregate reads, and
375
+ find-or-create roots by business key (`conflictTarget`).
@@ -0,0 +1,189 @@
1
+ # Feature Areas - Hierarchical Authz Grouping
2
+
3
+ Group related features under one **area** folder. The area's `_area.ts` file declares a route
4
+ prefix, admission lanes, and an authorization vocabulary — relationships, roles, rules, tenant
5
+ anchors, scope kinds — that every feature **inside the folder** inherits by name. Features
6
+ outside the folder cannot reference any of it: the compiler fails the build.
7
+
8
+ > Naming note: this concept is an **area**. `domain` in Quickback always means a DNS custom
9
+ > domain (see [custom domains](/compiler/config/domains)).
10
+
11
+ ## Why
12
+
13
+ Cross-cutting authz for a concept like a project, an event, or a location used to live in the
14
+ root `quickback.config.ts` and was wired to its consumers by a path-prefix string across a flat
15
+ feature list. An area makes the grouping **structural**: the folder *is* the boundary, the
16
+ `_area.ts` *is* the single declaration site, and the compiler enforces that the vocabulary
17
+ never leaks outside the subtree.
18
+
19
+ ## Layout
20
+
21
+ ```
22
+ quickback/features/
23
+ ├── workspace/ ← AREA (has _area.ts)
24
+ │ ├── _area.ts ← defineArea({...})
25
+ │ ├── projects.ts ← the area folder may itself be a feature
26
+ │ ├── project_collaborators.ts
27
+ │ ├── tasks/ ← child feature
28
+ │ │ ├── tasks.ts
29
+ │ │ └── actions/addTask.ts
30
+ │ └── chat/ ← child feature
31
+ │ └── actions/postMessage.ts
32
+ └── billing/ ← flat feature (unchanged)
33
+ ```
34
+
35
+ Reserved sub-directories (`actions/`, `handlers/`, `lib/`, `pages/`) are never child features. A directory
36
+ **without** `_area.ts` is a leaf feature — its unreserved subdirectories are not loaded, and a
37
+ subdirectory containing `defineTable(...)` / `defineAction(...)` **fails the compile** (silent
38
+ route/table disappearance after a mis-move is the failure mode areas must never introduce).
39
+ Feature leaf names stay globally unique — they key `src/features/<name>/` in the output, so
40
+ moving a feature into an area changes nothing about its generated identity.
41
+
42
+ ## `_area.ts`
43
+
44
+ ```typescript
45
+ // features/workspace/_area.ts
46
+ import { defineArea } from '@quickback/compiler';
47
+
48
+ export default defineArea({
49
+ // Namespace identity — drives the emitted routes file name and errors.
50
+ name: 'projectScope',
51
+
52
+ // Inherited route mount + admission gate. Optional: an area with no
53
+ // prefix contributes shared vocabulary only. A prefix REQUIRES at least
54
+ // one `via` lane (a mounted prefix with no gate would be ungated).
55
+ prefix: '/project/:projectId',
56
+ via: ['collaboratorOf', { roles: ['admin', 'owner'] }],
57
+ mintScope: true,
58
+ acceptScope: 'project',
59
+
60
+ // Area-owned vocabulary — the EXACT same shapes as the root authz blocks.
61
+ relationships: {
62
+ collaboratorOf: {
63
+ from: 'project_collaborators',
64
+ subject: { column: 'collaboratorUserId', equals: 'ctx.userId' },
65
+ resource: { column: 'projectId' },
66
+ where: { status: 'active' },
67
+ loads: 'projects',
68
+ exposeAs: 'project',
69
+ },
70
+ },
71
+ roles: {
72
+ projectStaff: { or: [{ via: 'collaboratorOf' }, { roles: ['admin', 'owner'] }] },
73
+ },
74
+ scopes: {
75
+ project: {
76
+ requestField: 'projectId',
77
+ roles: { collaborator: { via: 'collaboratorOf', subject: 'both' } },
78
+ },
79
+ },
80
+ // Named gates + tenant anchors work too — same shapes as authz.rules /
81
+ // authz.tenants, visible to this subtree only.
82
+ });
83
+ ```
84
+
85
+ A descendant feature references everything by bare name — no imports, no root declaration:
86
+
87
+ ```typescript
88
+ // features/workspace/tasks/actions/addTask.ts
89
+ export default defineAction({
90
+ path: './tasks/add', // relative → /project/:projectId/tasks/add
91
+ access: { roles: ['projectStaff'] }, // resolves against the area
92
+ // ...
93
+ });
94
+ ```
95
+
96
+ ## The visibility contract
97
+
98
+ An area's names are visible to **its own subtree only** (the area folder, its features, and
99
+ nested areas). The compiler checks **every** reference channel — access `roles:` arrays
100
+ (including named gates and both spellings of scoped roles: bare aliases and
101
+ `scope:<kind>:<role>`), action `access` and `anchor:`, firewall `via:` arms,
102
+ `ctx.scope.<kind>` accessors, `{ rule }` and `{ tenant }` firewall references, auth-view
103
+ `tenant:` includes, `realtime.requiredRoles`, table-level `namespace.via` lanes, and other
104
+ `_area.ts` nodes. Referencing an area name from outside is always a compile error:
105
+
106
+ ```
107
+ Feature "billing" ... references role "projectStaff" declared by area "projectScope"
108
+ (features/workspace/_area.ts), but this site is not inside that area. ... move the
109
+ referencing code under the declaring area, or lift the declaration to root authz if it
110
+ is genuinely global.
111
+ ```
112
+
113
+ Two structural rules keep the fold sound:
114
+
115
+ - **No overrides (v1).** Re-declaring an inherited name — in any class, including scope kinds,
116
+ scoped-role aliases, and namespace names — is a compile error. Declare each name in exactly
117
+ one place. (`overrides:` marker syntax is reserved for a future release.)
118
+ - **Declaration-site rule.** Root `authz` bodies (roles, rules, tenants, scopes, namespaces)
119
+ may reference **root-declared names only** — a root definition is visible everywhere and
120
+ would launder an area name out of its subtree. An area's bodies may reference root ∪
121
+ ancestors ∪ self.
122
+
123
+ One deliberate exception: root-config **namespace-identity wiring** — today exactly
124
+ `realtime.wsTicket.namespace` — may name an area's namespace. It attaches the area's complete
125
+ gate (its full lane set) and constructs no new grant. Such consumers are listed in the
126
+ manifest under the owning area.
127
+
128
+ ## Containment and the `route: 'self'` marker
129
+
130
+ The area's prefix is an audited surface:
131
+
132
+ - A feature **outside** the area may not declare an action path (or a table-level
133
+ `namespace` prefix) under the area's prefix — compile error.
134
+ - A project-level `authz.namespaces` entry the area does **not** own — root-declared, or
135
+ another area's — may not carve a prefix at or under the area's prefix. Namespace claiming
136
+ is longest-prefix-wins, so such an entry would silently re-gate the area's descendant
137
+ actions with its own `via` lanes — compile error. (A *descendant* feature's table-level
138
+ namespace inside the prefix is legal; the manifest attributes its claimed actions to that
139
+ namespace, not to the area.)
140
+ - A **descendant** action whose absolute path is *outside* the prefix opts out of the area's
141
+ admission gate and is gated solely by its own `access:`. That must be explicit:
142
+ mark the action `route: 'self'`, or the compile fails (a typo'd prefix must never silently
143
+ self-gate). The marker is equally rejected where it is dead — on in-prefix actions and in
144
+ features outside any mounted area. Every self-gated action is listed in the manifest.
145
+
146
+ Relative paths (`path: './…'`) resolve against the area prefix. Dot segments (`.` / `..`) are
147
+ rejected outright — the resolved route must stay under the prefix.
148
+
149
+ ## Nested areas
150
+
151
+ Areas nest to arbitrary depth. A nested area may declare additional **vocabulary** freely. A
152
+ nested area may **not** mount its own `prefix` under an ancestor that already mounts one:
153
+ per-level nested admission is *unlinked* (a caller related to child instance S under parent A
154
+ would be admitted at `/a/A/s/S` even when S belongs to parent B), and Quickback refuses to
155
+ compile an unlinked gate. Mount one prefix per chain, or keep the nested area
156
+ vocabulary-only.
157
+
158
+ ## The capability floor: `requires: ['feature-areas']`
159
+
160
+ An area-tree project **must** declare the marker in `quickback.config.ts`:
161
+
162
+ ```typescript
163
+ export default defineConfig({
164
+ // ...
165
+ requires: ['feature-areas'],
166
+ });
167
+ ```
168
+
169
+ Any CLI — including one that predates areas — passthrough-executes the config, so the marker
170
+ always reaches the compiler. A current compiler that sees the marker but no `areas` payload
171
+ rejects the compile with an upgrade message instead of silently compiling a project whose
172
+ nested features an old CLI never loaded (which would otherwise generate destructive
173
+ migrations). In the other direction, a current CLI refuses output from a compiler that
174
+ predates areas.
175
+
176
+ ## The authz manifest
177
+
178
+ Area projects emit `quickback/authz-manifest.json` on every compile — the audit inventory the
179
+ flat config can no longer answer from one file: the area tree, every folded name and its
180
+ declaring file, per-area member features, `areaGatedActions` vs `selfGatedActions`, and any
181
+ root-config namespace consumers. Review it in PRs the way you review the security reports;
182
+ the generated `AGENTS.md` also gains a feature-areas section so coding agents place new
183
+ features correctly.
184
+
185
+ ## What belongs at root
186
+
187
+ Root `authz` remains the home for genuinely global vocabulary — names used across areas or by
188
+ flat features. Everything scoped to one concept belongs in that concept's `_area.ts`. When in
189
+ doubt: if only one folder's features reference it, it belongs in that folder's area.
@@ -88,6 +88,13 @@ Same object, two names — pick one.
88
88
 
89
89
  ## Feature directory layout
90
90
 
91
+ Feature directories normally sit flat under `features/`. To group several features under one
92
+ authz concept (a shared route prefix + shared relationships/roles/scopes), put them inside an
93
+ **area** folder carrying `_area.ts` — see [Feature areas](/compiler/definitions/feature-areas).
94
+ Reserved sub-directories (`actions/`, `lib/`, `pages/`) are never child features, and a
95
+ subdirectory of a NON-area feature containing `defineTable(...)`/`defineAction(...)` fails the
96
+ compile (nested features load only under an area).
97
+
91
98
  A feature directory holds tables, optional shared schemas, and the handler files that back any actions:
92
99
 
93
100
  ```
@@ -111,6 +118,32 @@ Three things to know:
111
118
 
112
119
  For everything action-related — three modes, conflict rules, the `_feature.ts` shape — see [Actions](/compiler/definitions/actions).
113
120
 
121
+ ## Composition vs reference — `owns`
122
+
123
+ A schema-level FK (`references:` / `.references()`) says "this row points at
124
+ that row." It does **not** say who owns whom. When a set of child rows has no
125
+ lifecycle of its own — junction memberships, normalized phones/emails, line
126
+ items — declare the composition with `owns` on the root table:
127
+
128
+ ```ts
129
+ export default feature("projects", {
130
+ // ...
131
+ owns: {
132
+ tasks: { table: "tasks", fk: "projectId", inherit: ["organizationId"] },
133
+ members: { table: "projectMembers", fk: "projectId", refs: { personId: "people" }, inherit: ["organizationId"] },
134
+ },
135
+ });
136
+ ```
137
+
138
+ That single fact generates the whole aggregate write path — one atomic
139
+ changeset request over the root plus its owned relations, every op paying the
140
+ child's own firewall/access/guards. Keep plain `references` for pointers at
141
+ independent entities (those go in the relation's `refs`, existence-checked
142
+ per-tenant). Contract v2 only. Full reference:
143
+ [changesets](/compiler/definitions/changesets) — including the per-op
144
+ `routes: false` knob for widening a child's access for changeset use without
145
+ mounting its raw route.
146
+
114
147
  ## Handlers — one `q` namespace for everything
115
148
 
116
149
  Custom action handlers need to run queries against the database. Quickback's compiled projects expose the Drizzle query-builder helpers on the same `q` namespace you use for schema authoring, so handler code stays inside one DSL: