@quickback-dev/cli 0.61.1 → 0.64.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/dist/commands/compile.d.ts +11 -0
  2. package/dist/commands/compile.d.ts.map +1 -1
  3. package/dist/commands/compile.js +47 -12
  4. package/dist/commands/compile.js.map +1 -1
  5. package/dist/index.js +4 -2
  6. package/dist/index.js.map +1 -1
  7. package/dist/skill/docs/api/crud.md +17 -0
  8. package/dist/skill/docs/changelog/index.md +179 -1
  9. package/dist/skill/docs/configure/auth.md +2 -1
  10. package/dist/skill/docs/configure/index.md +13 -13
  11. package/dist/skill/docs/define/actions/defining.md +18 -5
  12. package/dist/skill/docs/define/actions/index.md +73 -0
  13. package/dist/skill/docs/define/feature.md +2 -1
  14. package/dist/skill/docs/define/scopes.md +9 -4
  15. package/dist/skill/docs/platform/api-contract/index.md +42 -11
  16. package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -2
  17. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +3 -1
  18. package/dist/skill/docs/tooling/output.md +21 -0
  19. package/package.json +1 -1
  20. package/src/skill/docs/api/crud.md +17 -0
  21. package/src/skill/docs/changelog/index.md +179 -1
  22. package/src/skill/docs/configure/auth.md +2 -1
  23. package/src/skill/docs/configure/index.md +13 -13
  24. package/src/skill/docs/define/actions/defining.md +18 -5
  25. package/src/skill/docs/define/actions/index.md +73 -0
  26. package/src/skill/docs/define/feature.md +2 -1
  27. package/src/skill/docs/define/scopes.md +9 -4
  28. package/src/skill/docs/platform/api-contract/index.md +42 -11
  29. package/src/skill/docs/platform/auth/jwt-optimization.md +2 -2
  30. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +3 -1
  31. package/src/skill/docs/tooling/output.md +21 -0
@@ -81,11 +81,24 @@ Before sending a compile request, the CLI loads each action in an isolated
81
81
  local bundle and converts `action.input` plus an optional `action.output` with
82
82
  Zod 4's `z.toJSONSchema`. It does not call `execute`; the hosted compiler never
83
83
  evaluates project code. The output contract feeds OpenAPI and
84
- `Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`. Under
85
- contract v2, every action input must produce a schema; output remains optional.
86
- A failure names the exact
87
- action, whether bundling or evaluation failed, and the underlying local error.
88
- V1 can still fall back to the lower-fidelity static schema parser.
84
+ `Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
85
+
86
+ **Every action input must produce a schema, on every contract version.** Since
87
+ v0.63.0 a failed harvest fails the compile, naming the exact action, whether
88
+ bundling or evaluation failed, and the underlying local error. Output remains
89
+ optional.
90
+
91
+ **Why it fails instead of degrading.** The compiler's static fallback parser
92
+ reads your Zod as text and can only produce `type` and `properties`. It never
93
+ emits `required` or `additionalProperties` — so a fallback request schema looks
94
+ fully typed in `openapi.json` and the MCP tool list while enforcing nothing:
95
+ generated clients treat every required field as optional, and unknown keys pass.
96
+ Constructs it cannot parse at all degrade further, to a bare `{}` with no
97
+ `properties`. Neither is visible in a diff.
98
+
99
+ `--allow-degraded-schemas` restores the old degrade-and-continue behavior for a
100
+ single compile. It still prints every action that fell back and why, and the
101
+ compiler warns again with the count and sampled paths.
89
102
 
90
103
  Bare imports are resolved from the generated runtime's configured
91
104
  `build.outputDir/node_modules` first. If definitions live in `quickback/` and
@@ -91,6 +91,79 @@ For shared Zod schemas or helpers, put them under `<feature>/lib/` and import
91
91
  from each action file. Files under `lib/` are copied verbatim into the
92
92
  generated output.
93
93
 
94
+ ## Replace a CRUD verb
95
+
96
+ CRUD routes are compiler-owned. When a live `POST /messages` (or
97
+ `PATCH` / `DELETE /:id`) has to grow — side effects, a different body, a
98
+ protocol-shaped response — map that verb to a named action. The URL, OpenAPI
99
+ operation id, and MCP tool stay; `execute` becomes the handler.
100
+
101
+ {/* doc-compile: skip — two files (table + action); the gate compiles each fence as an isolated project. */}
102
+ ```ts
103
+ // features/messages/messages.ts
104
+ export default feature("messages", {
105
+ columns: { /* … */ },
106
+ read: { access: { roles: ["member"] } },
107
+ create: {
108
+ access: { roles: ["member"] },
109
+ action: "send", // features/messages/actions/send.ts
110
+ },
111
+ update: { access: { roles: ["member"] } },
112
+ delete: { access: { roles: ["admin"] } },
113
+ });
114
+ ```
115
+
116
+ ```ts
117
+ // features/messages/actions/send.ts
118
+ import { z } from "zod";
119
+ import { defineAction, messages } from "../.quickback/define-action";
120
+
121
+ export default defineAction({
122
+ description: "Send a message",
123
+ path: "/messages", // must equal the collection URL
124
+ method: "POST",
125
+ input: z.object({ body: z.string().min(1) }),
126
+ access: { roles: ["member"] },
127
+ async execute({ db, input, ctx }) {
128
+ const [row] = await db.insert(messages).values({
129
+ body: input.body,
130
+ organizationId: ctx.activeOrgId!,
131
+ }).returning();
132
+ return row;
133
+ },
134
+ });
135
+ ```
136
+
137
+ Expected:
138
+
139
+ - `POST /api/v1/messages` runs `send`'s `execute`. Status is `201`.
140
+ - OpenAPI / MCP keep `createMessages` (or the table's CRUD operation id). The
141
+ request body is the action's `input`, not the table's createable fields.
142
+ - Unmapped verbs keep the generated handler. Mapping is per-verb.
143
+ - The action's own route is not mounted — there is no second `POST /messages/send`.
144
+ - Auto-promoted `POST /batch` is suppressed (the stock batch would skip `send`).
145
+ Set `batch: false` explicitly if you also declare a batch config.
146
+
147
+ ### Composition
148
+
149
+ Fail-closed, one rule:
150
+
151
+ | Layer | Who owns it |
152
+ |---|---|
153
+ | URL, method, operation id | The CRUD verb |
154
+ | Access | Both: `create.access` AND the action's `access` must pass |
155
+ | Guards | Skipped — the action's `input` is the body contract |
156
+ | Firewall | Table firewall on update/delete record fetch; create uses scoped `db` in `execute` |
157
+
158
+ ### Compile errors
159
+
160
+ The compile fails if the named action is missing, bound to a different table,
161
+ the wrong shape (create needs a standalone `path:` equal to the collection URL;
162
+ update/delete need a record-based action with no `path:`), declares a
163
+ conflicting `method`, is already mapped to another verb, or the table also
164
+ declares `owns` (changeset dispatch lives on the stock handler). `read.action`
165
+ is not supported.
166
+
94
167
  ## The rest of this section
95
168
 
96
169
  - **[Defining actions](/define/actions/defining)** — the action file, its configuration options, protected fields, and refs
@@ -15,7 +15,7 @@ feature("name", {
15
15
  // Security — the five pillars
16
16
  firewall: {}, // which ROWS (auto-derived from organizationId / ownerId / teamId)
17
17
  read: {}, // who may read + `views` — named column projections
18
- create: {}, // who may write
18
+ create: {}, // who may write — `action: "send"` maps the URL to an action file
19
19
  update: {},
20
20
  delete: {}, // + `mode: "soft" | "hard"`
21
21
  guards: {}, // which FIELDS a caller may set
@@ -41,6 +41,7 @@ feature("name", {
41
41
  | Tenant isolation, role gates, field and value control | `firewall`, `read`/`create`/`update`/`delete`, `guards`, `masking` | [Security](/define/security) |
42
42
  | A narrower shape for a broader audience | `read.views` | [Views](/define/views) |
43
43
  | `publish` / `approve` / `checkIn` — a state change | `transitions` | [Transitions](/define/transitions) |
44
+ | A live CRUD URL that needs custom `execute` | `create.action` / `update.action` / `delete.action` | [Actions](/define/actions#replace-a-crud-verb) |
44
45
  | A side-effect or data rule on every write | `triggers` | [Triggers](/define/triggers) |
45
46
  | Parent plus its children written atomically | `owns` | [Changesets](/define/changesets) |
46
47
  | Clients updated live | `realtime` | [Realtime](/platform/realtime/using-realtime) |
@@ -60,10 +60,14 @@ The server probes **every declared role** for the proposed instance (one DB touc
60
60
 
61
61
  ```jsonc
62
62
  // a shuttle driver who is also a confirmed guest
63
- "scope": { "event": { "id": "evt_123", "roles": ["attendee", "shuttleDriver"], "shuttleId": "shA" } }
63
+ "scope": { "event": { "id": "evt_123", "roles": ["attendee", "shuttleDriver"], "shuttleId": "shA", "sctMs": "m1700000000000" } }
64
64
  ```
65
65
 
66
- The client sends that JWT as `Authorization: Bearer …` on subsequent requests. The auth middleware verifies the signature and sets `ctx.scope` — **no DB**. The claim is carried forward on every authed call (rolling refresh) for up to **15 minutes from the last actual relationship proof** — the mint stamps a proof timestamp (`sct`) that the refresh carries forward verbatim and checks against the carry-forward cap. Past the cap the refresh stops, the token expires within one TTL, and the client re-proves via `enter` (or any namespace route that mints) to restart the window.
66
+ `sctMs` is on **every** entry: the server's proof timestamp for that kind (epoch milliseconds, written `m<ms>`) — see [Revocation & TTL](#revocation--ttl). The examples below elide it to keep the key under discussion in view.
67
+
68
+ The client sends that JWT as `Authorization: Bearer …` on subsequent requests. The auth middleware verifies the signature and sets `ctx.scope` — **no DB**. The claim is carried forward on every authed call (rolling refresh) for up to **15 minutes from the last actual relationship proof** — the mint stamps a proof timestamp that the refresh carries forward verbatim and checks against the carry-forward cap. Past the cap the refresh stops, the token expires within one TTL, and the client re-proves via `enter` (or any namespace route that mints) to restart the window.
69
+
70
+ The proof timestamp is **per scope kind**. A mint proves the kind it was asked for and carries every other kind forward *with the stamp it already had* (`sctMs` on the entry, epoch milliseconds written `m<ms>`), so entering one relationship never extends — or resurrects — another. Re-proving `event` restarts `event`'s window and nothing else.
67
71
 
68
72
  > **Invariant:** the client only *proposes* the instance id (from the URL). The server proves membership before signing. No client-asserted scope is ever trusted.
69
73
 
@@ -631,11 +635,11 @@ the socket gate stay identical for accountless principals too.
631
635
  The scope claim is trusted between proofs — it is never re-checked against the database while it rides. Two bounds keep that window finite:
632
636
 
633
637
  - **The TTL** (default 180s, `auth.jwt.expiresIn`, clamped ≤180s on scope-bearing tokens) bounds an *idle* client: a token that stops being used dies within one TTL.
634
- - **The carry-forward cap** (15 minutes) bounds an *active* client: the rolling refresh re-signs the claim on every authed call, but only while the claim's proof timestamp (`sct`, stamped exclusively by the proven mint sites) is younger than the cap. Past it the refresh refuses, the token expires, and the next `enter` (or namespace-route mint) re-probes the relationship — which won't re-mint a revoked role.
638
+ - **The carry-forward cap** (15 minutes) bounds an *active* client: the rolling refresh re-signs the claim on every authed call, but only while its proof timestamp (stamped exclusively by the proven mint sites) is younger than the cap. The cap is applied **per scope kind** — a kind whose own proof is past it is dropped from the re-signed claim, so re-proving one relationship cannot roll another forward. Past the cap the refresh refuses, the token expires, and the next `enter` (or namespace-route mint) re-probes the relationship — which won't re-mint a revoked role.
635
639
 
636
640
  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:
637
641
 
638
- - **`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 (`sct`, with its millisecond companion `sctMs`) is at or before it — no same-second gap. Both halves of the proof time are carried forward verbatim by the rolling refresh; a refresh never substitutes its own mint time for proof time. The check fails closed — a scope claim whose revocation state can't be read is not trusted either. See [auth config](/configure/auth).
642
+ - **`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).
639
643
  - **`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.
640
644
 
641
645
  ## Reference
@@ -662,6 +666,7 @@ ctx.mintScope(opts: { via: string; subject: string; setAuthToken?: boolean }):
662
666
  - `requestField` must equal every role-relationship's `resource.column`.
663
667
  - Each relationship's `from` table must exist and ship a generated firewall (it can't be `exception`).
664
668
  - A `subKeys` entry ending in `[]` is **set-valued** (lowers to `inArray`, minted as `string[]`); without the marker it's scalar (`eq`, minted as `string`).
669
+ - `id`, `roles`, `subjectId`, and `sctMs` are **reserved** on the claim entry — the mint owns them, so a `subKeys` entry of that name is a compile error rather than a row value overwriting proven state.
665
670
  - `subject` defaults to `'user'`. `'supplied'`/`'both'` enable [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) (sessionless mint); `'supplied'` is **not** mintable via `/scope/v1/enter`.
666
671
  - `ctx.mintScope({ via, subject })` mints a **scope-only** token (no user identity, `ctx.userId` undefined) from the `from`-row whose PK is `subject` — reading the role, resource id, sub-keys, and `subjectId` off that row.
667
672
  - `subjectId` is the conferring row's primary key, populated on **both** proof paths — scope self-data on `ctx.scope.<kind>.subjectId`.
@@ -4,15 +4,16 @@ Every generated API speaks one public HTTP contract, selected once per project:
4
4
 
5
5
  ```ts title="quickback/quickback.config.ts"
6
6
  export default defineConfig({
7
- // Omitted = v1 (the pinned compatibility mode for already-deployed clients).
7
+ // Omitted = v2 semantics on /api/v1. Pin "v1" to opt out.
8
8
  contract: { version: "v2" },
9
9
  // ...
10
10
  });
11
11
  ```
12
12
 
13
- **v2 is the flagship contract.** Everything new lands on v2; projects pinned to
14
- v1 keep today's byte-stable wire and receive no new contract features until
15
- they migrate.
13
+ **v2 is the flagship contract, and the default since v0.64.0.** Everything new
14
+ lands on v2; a project pinned to v1 keeps the byte-stable legacy wire and
15
+ receives no new contract features until it migrates. Your URLs are a separate
16
+ choice — see [below](#two-axes-semantics-and-routes).
16
17
 
17
18
  ## Response envelope
18
19
 
@@ -111,10 +112,39 @@ export default defineAction({
111
112
  });
112
113
  ```
113
114
 
115
+ ## Two axes: semantics and routes
116
+
117
+ `contract` has two independent keys, and conflating them is the most common
118
+ mistake:
119
+
120
+ | Key | Controls | Default |
121
+ |---|---|---|
122
+ | `version` | Semantics — framing, strictness, the auth lane | `'v2'` |
123
+ | `routes` | The URL prefix, and nothing else | `'v1'` |
124
+
125
+ So a project with no `contract` block **runs the v2 contract on `/api/v1`.**
126
+ Taking the flagship semantics does not move your URLs, and moving your URLs
127
+ does not change your semantics.
128
+
129
+ {/* doc-compile: skip — config fragment, not a compilable project */}
130
+ ```typescript
131
+ contract: { version: "v1" } // opt out of v2 semantics
132
+ contract: { routes: "v2" } // serve on /api/v2, keep v1 semantics
133
+ contract: { version: "v2", routes: "v2" } // both — the pre-v0.64.0 "v2"
134
+ ```
135
+
136
+ **This changed in v0.64.0.** Before it, `version: 'v2'` moved the URLs too, and
137
+ the default was `'v1'` on both axes. A project that pinned `version: 'v2'` to
138
+ get `/api/v2` must now add `routes: 'v2'` to keep those URLs.
139
+
140
+ **Pinning your CLI version does not pin the contract.** The default lives in the
141
+ compiler, which is a hosted service — an older CLI inherits it too. The config
142
+ key is the only pin.
143
+
114
144
  ## Contract version matrix
115
145
 
116
- Flipping `contract.version` moves the **entire** contract at once — plan the
117
- client migration as one move:
146
+ `version` moves everything in this table except the three base paths, which
147
+ follow `routes`:
118
148
 
119
149
  | Surface | v1 (pinned) | v2 (flagship) |
120
150
  |---|---|---|
@@ -128,12 +158,13 @@ client migration as one move:
128
158
  | Aggregate changesets (`application/vnd.quickback.changeset+json` on PATCH/POST, [`owns`](/define/changesets)) | not available | available where `owns` is declared |
129
159
  | Bare `?fields=` unknown names | silently dropped | **400** |
130
160
  | `fields[<fk>]=` unknown names | n/a | **400** |
131
- | Action input schemas | best-effort static parse | complete client-side harvest **required** |
161
+ | Action input schemas | complete client-side harvest **required** (since v0.63.0) | complete client-side harvest **required** |
132
162
 
133
- Sequencing a migration: ship clients that speak the v2 paths, CloudEvents
134
- frames, and session-first auth (or declare `auth.jwt`); confirm webhook
135
- consumers validate the `webhook-*` headers; then flip the switch. Until then
136
- v1 stays byte-identical.
163
+ Sequencing a migration: the URL row is the only one you can defer with
164
+ `routes`. For the rest — ship subscribers that parse CloudEvents frames, move
165
+ webhook consumers onto the `webhook-*` headers (v1 already sends **both** sets,
166
+ so that step needs no coordination), and either adopt session-first auth or
167
+ declare `auth.jwt`. Pin `version: "v1"` while that work lands.
137
168
 
138
169
  ## Machine-readable contract
139
170
 
@@ -31,7 +31,7 @@ The JWT encodes everything needed for auth middleware:
31
31
  | `iatMs` | Issued-at in epoch **milliseconds** — Quickback ordering metadata, not a standard claim. Same clock sample as `iat`, set by the signer only. Lets [revocation](#revocation--revocationcheck-kv) order a token against a marker written in the same second |
32
32
  | `exp` | Expiry — **180 seconds** (3 minutes) after `iat` by default; set via [`auth.jwt.expiresIn`](/configure/auth) |
33
33
 
34
- Scope-bearing tokens also carry `sct` (proof timestamp, unix seconds) and its millisecond companion `sctMs` — see [Scopes](/define/scopes). Read `iat` / `sct` from external tooling; `iatMs` / `sctMs` exist only so revocation can break ties inside a second.
34
+ Scope-bearing tokens also carry `sct` (proof timestamp, unix seconds) and its millisecond companion `sctMs`, plus a per-kind `sctMs` stamp (`m<ms>`) inside each `scope.<kind>` entry — a mint proves one kind and carries the others forward with the proof time they already had. See [Scopes](/define/scopes). Read `iat` / `sct` from external tooling; the millisecond values exist only so revocation can break ties inside a second.
35
35
 
36
36
  ### Signing
37
37
 
@@ -116,7 +116,7 @@ auth: {
116
116
  },
117
117
  ```
118
118
 
119
- 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 `sct`/`sctMs` for the scope claim) is **at or before** the stored timestamp. Cost: 2+ edge-cached KV reads per bearer verify.
119
+ 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.
120
120
 
121
121
  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).
122
122
 
@@ -1,6 +1,8 @@
1
1
  # Endpoints
2
2
 
3
- The cloud compiler API is hosted at `https://compiler.quickback.dev`.
3
+ The cloud compiler API is hosted at `https://compiler.quickback.dev`
4
+ (alias: `https://build.quickback.dev` — same Worker, same auth via
5
+ `quickback-api`, identical `/health` / `/templates` / `/compile`).
4
6
 
5
7
  ## Public (No Auth)
6
8
 
@@ -184,6 +184,27 @@ authentication behavior. Quickback preserves unrelated overrides already in
184
184
  your package manifest, but the compiler-owned Lodash security pin wins if an
185
185
  existing override conflicts.
186
186
 
187
+ A project that declares an in-worker Durable Object also gets `hono-party`
188
+ plus a second entry in the same block:
189
+
190
+ ```json
191
+ {
192
+ "overrides": {
193
+ "hono-party": {
194
+ "@cloudflare/workers-types": "$@cloudflare/workers-types"
195
+ }
196
+ }
197
+ }
198
+ ```
199
+
200
+ `hono-party` still declares a peer dependency on `@cloudflare/workers-types`
201
+ major 4, which cannot be satisfied alongside the major 5 the compiler pins, so
202
+ a plain `npm install` would fail with `ERESOLVE`. The override is scoped to
203
+ `hono-party` — nothing else in the tree is relaxed — and the `$` form resolves
204
+ to whatever your `package.json` already declares, so it tracks the pin instead
205
+ of drifting from it. Projects without an in-worker Durable Object do not get
206
+ this entry.
207
+
187
208
  After recompiling, run your package manager's install command so its lockfile
188
209
  records the patched transitive version. Use `npm audit --omit=dev` when
189
210
  evaluating the production dependency tree; development-tool advisories are a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.61.1",
3
+ "version": "0.64.0",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -55,6 +55,23 @@ For a resource named `jobs`, Quickback generates:
55
55
  | `PUT` | `/jobs/:id` | Upsert a record (requires config) |
56
56
  | `PUT` | `/jobs/batch` | Batch upsert multiple records (requires config) |
57
57
 
58
+ ## Replace a generated verb with an action
59
+
60
+ Map `create`, `update`, or `delete` to a named action when the public URL
61
+ must stay and the handler has to become real code. See
62
+ [Replace a CRUD verb](/define/actions#replace-a-crud-verb).
63
+
64
+ {/* doc-compile: skip — one-key excerpt; the whole-file form is on the actions page. */}
65
+ ```ts
66
+ create: {
67
+ access: { roles: ["member"] },
68
+ action: "send",
69
+ }
70
+ ```
71
+
72
+ `POST /api/v1/jobs` then runs `send`'s `execute`. Clients, OpenAPI, and MCP
73
+ keep the CRUD path and operation id. Unmapped verbs are unchanged.
74
+
58
75
  ## List & Get Records
59
76
 
60
77
  `GET /{resource}` and `GET /{resource}/:id` are part of the [read pipeline](/define/read). Configuration (access, pagination, view projections) lives under `read:`. Filtering, sorting, and pagination query parameters work the same on both endpoints — see [Query Parameters](/api/query-params).
@@ -8,7 +8,185 @@ The current release series. Older entries are archived by version range:
8
8
  - [v0.20 – v0.29](/changelog/v0.2x)
9
9
  - [v0.18 and earlier](/changelog/v0.1x)
10
10
 
11
- ## Unreleased
11
+ ## v0.64.0 — August 15, 2026
12
+
13
+ ### `contract.version` defaults to v2 — and no longer moves your URLs
14
+
15
+ **Semantics and routes are now independent axes.**
16
+
17
+ | Key | Controls | Default |
18
+ |---|---|---|
19
+ | `version` | Framing, strictness, the auth lane | `'v2'` |
20
+ | `routes` | The URL prefix, nothing else | `'v1'` |
21
+
22
+ A project with no `contract` block runs the **v2 contract on `/api/v1`**. You
23
+ inherit the flagship semantics; your clients keep calling the address they
24
+ already call.
25
+
26
+ Previously these were one knob: `version: 'v2'` moved `/api`, `/auth`, and
27
+ `/broadcast` to `/v2` as a side effect of selecting v2 behavior. That coupling
28
+ made the better contract expensive to adopt for the wrong reason — a URL
29
+ migration nobody asked for.
30
+
31
+ **Breaking — action required if you pinned `version: 'v2'` for the URLs.**
32
+ Add `routes: 'v2'` to keep serving `/api/v2`:
33
+
34
+ ```typescript
35
+ contract: { version: "v2", routes: "v2" }
36
+ ```
37
+
38
+ Without it, a previously-v2 project moves back to `/api/v1` on its next
39
+ compile. Semantics are unaffected either way.
40
+
41
+ ### What the v2 default changes on the wire
42
+
43
+ URLs do not move. These do:
44
+
45
+ - Realtime frames become CloudEvents 1.0 envelopes. The largest change — every
46
+ subscriber re-parses. Routing info moves to `type`, payload to `data`.
47
+ - Outbound webhooks are signed Standard-Webhooks-only; the legacy
48
+ `X-Webhook-*` headers stop being sent. v1 already sent **both** sets, so
49
+ consumers can migrate to `webhook-signature` before upgrading and the flip
50
+ becomes a no-op for them.
51
+ - Unknown `?fields=` names return `400` instead of being silently dropped.
52
+ - The Quickback HMAC-JWT lane is off unless `auth.jwt` is declared.
53
+ - `?include=`, aggregate changesets (`owns`), and delegated principals become
54
+ available without a pin.
55
+
56
+ Pin `contract: { version: "v1" }` to opt out. Every compile that leaves
57
+ `contract.version` unset warns once, naming what changed.
58
+
59
+ ### Action-schema harvest no longer keys on contract version
60
+
61
+ `assertCompleteActionInputSchemas` fired whenever the contract was v2 and any
62
+ harvested schema was absent. With v2 as the default that would have failed
63
+ every [Start](https://start.quickback.dev) project containing an action —
64
+ `rawFiles` callers post project source and never execute action code, so they
65
+ cannot harvest at all.
66
+
67
+ The gate now fires only on a **partial** payload: some schemas supplied,
68
+ others missing. Callers that supply none get the coverage warning instead. The
69
+ CLI has failed closed on its own since v0.63.0, with the local per-action
70
+ reason the compiler cannot know.
71
+
72
+ ### Fixes
73
+
74
+ - CloudEvents framing was derived from `broadcastBase.endsWith('/v2')`. Once
75
+ routes and semantics decoupled, that silently reverted every default project
76
+ to raw v1 frames. Framing is now passed explicitly.
77
+ - The bundled CMS/Account SPAs gated their base-path override on *semantics*
78
+ when it is a *routes* concern, emitting a redundant `/api/v1` override for
79
+ every new project.
80
+
81
+ ## v0.63.0 — August 14, 2026
82
+
83
+ ### Action input schemas now fail the compile instead of degrading
84
+
85
+ **Affects every project with actions, on every contract version.**
86
+
87
+ The CLI harvests each action's `input` locally with `z.toJSONSchema`. When an
88
+ action failed to harvest, the compiler fell back to a static parser that reads
89
+ Zod as text — and that parser cannot emit `required` or `additionalProperties`.
90
+ The resulting operation kept its `properties` and looked fully typed in
91
+ `openapi.json` and the MCP tool list while enforcing nothing: generated clients
92
+ treated required fields as optional and unknown keys passed. Constructs the
93
+ parser could not read at all degraded further, to a bare `{}`.
94
+
95
+ None of it was visible in a diff. One project shipped ~346 unenforced request
96
+ schemas this way; the change read as reformatting.
97
+
98
+ A failed harvest is now a compile error naming each action, whether bundling or
99
+ evaluation failed, and the underlying local error. This was previously the
100
+ behavior of `contract.version: 'v2'` only.
101
+
102
+ `quickback compile --allow-degraded-schemas` restores degrade-and-continue for a
103
+ single compile. It prints every action that fell back and why.
104
+
105
+ The compiler also warns when a caller supplies no schemas at all — `rawFiles`
106
+ callers such as the Start app cannot harvest — naming how many actions of the
107
+ total lost `required`, with sampled paths.
108
+
109
+ ### `contract.version` default flips to v2 in v0.64.0
110
+
111
+ An unset `contract.version` resolves to `'v1'` today. That default becomes
112
+ `'v2'` in **v0.64.0**. See the
113
+ [contract matrix](/platform/api-contract#contract-version-matrix).
114
+
115
+ > v0.64.0 shipped this **without** moving any URLs — semantics and routes became
116
+ > independent axes, so `/api/v1` stays put. This entry originally said the flip
117
+ > would move `/api/v1` → `/api/v2`; that is not what happened.
118
+
119
+
120
+ Every compile that leaves `contract.version` unset now warns. Pin
121
+ `contract: { version: "v1" }` to keep the current wire, or set `"v2"` to migrate
122
+ now.
123
+
124
+ **Pinning your CLI version does not pin the contract.** The default lives in the
125
+ compiler, which is a hosted service, so an older CLI inherits the flip too. The
126
+ config key is the only pin.
127
+
128
+ ### MCP tool grouping no longer assumes a `v1` path segment
129
+
130
+ Internal. Group derivation matched the literal segment `v1`, so a contract-v2
131
+ path would have fallen through and grouped under `api`. Operation tags take
132
+ precedence and every generated operation carries one, so no shipped tool list
133
+ was affected — the fallback is now correct for any `/api/v<n>/` prefix ahead of
134
+ the v0.64.0 default flip.
135
+
136
+ ## v0.62.0 — August 13, 2026
137
+
138
+ ### Security: `record:` access arms on `GET /:id` were never evaluated
139
+
140
+ **Affects any resource whose `read.access` contains a `record:` arm.**
141
+
142
+ A code rewrite corrupted `"$ctx.userId"` into `"$effectiveCtx.userId"` inside the
143
+ serialized access tree, and only the `$ctx.` prefix is recognised at runtime. The
144
+ arm therefore compared a column against the literal string and was permanently
145
+ false: a caller the config named was denied with 403 on the single-record read,
146
+ while the same tree admitted them everywhere else.
147
+
148
+ Those arms now evaluate. **Callers your config grants access to will start
149
+ receiving 200 where they previously received 403.** That is the documented
150
+ behavior being restored, not a widening — no caller is admitted whom the tree
151
+ does not name. Durable Object room gates already behaved correctly, so this also
152
+ removes a divergence where a room admitted a caller that `GET /:id` refused.
153
+
154
+ ### Security: revocation is per scope kind, not per token
155
+
156
+ **Affects projects using `authz.scopes`.**
157
+
158
+ A token carried one proof timestamp for a claim map whose kinds were proven at
159
+ different moments, so re-proving one kind restamped the others. A revoked kind
160
+ survived indefinitely as long as the caller kept re-proving any sibling.
161
+
162
+ Each entry now carries its own proof time, and both readers use it: the
163
+ revocation check, and the carry-forward cap. **The cap matters more** — it
164
+ applies on the default configuration, where `revocationCheck` is unset and no
165
+ KV marker is ever read, so it was the only bound on a carried claim.
166
+
167
+ Tokens minted before this release have no per-entry stamp and fall back to the
168
+ token-level proof time, conservatively. `authz.scopes[].roles[].subKeys` may no
169
+ longer declare `id`, `roles`, `subjectId`, or `sctMs` — those are server-minted,
170
+ and a row value overwriting one would forge a proof time. Compile fails naming
171
+ the path.
172
+
173
+ ### Generated projects with in-worker Durable Objects can install again
174
+
175
+ `npm install` failed with `ERESOLVE` immediately after a successful compile:
176
+ `hono-party` requires `@cloudflare/workers-types@^4`, and Quickback pins `^5`.
177
+ Unsatisfiable at any version — no `hono-party` release accepts 5.x.
178
+
179
+ Generated `package.json` now carries a scoped override so the peer resolves to
180
+ the project's own pin. Nothing outside `hono-party` is relaxed. Only projects
181
+ declaring an in-worker Durable Object receive it.
182
+
183
+ ### Fixed: two configurations that emitted uncompilable projects
184
+
185
+ - `plugins: { apiKey: false }` emitted a `problemJson(...)` call without its
186
+ import, so the generated project failed `tsc`.
187
+ - `organization: { allowUserToCreateOrganization: … }` in object form emitted the
188
+ key twice in one object literal (`TS1117`). `organizationHooks` had the same
189
+ collision and is now stripped from the merged options — the compiler owns it.
12
190
 
13
191
  ### `defineEmail` — inbound mail, provider-agnostic execute
14
192
 
@@ -109,7 +109,7 @@ Default `'none'`.
109
109
 
110
110
  `'kv'` (v0.45+, **Cloudflare runtime only**) keeps the fast-path stateless against the auth DB (still 0 D1 queries). There is nothing extra to provision — entries ride the `KV` binding every project already has, prefixed `qbrev:` and self-expiring after the maximum token lifetime, so the store never accumulates.
111
111
 
112
- A token is rejected when its mint timestamp (`iat`/`iatMs`, or `sct`/`sctMs` for the relationship-scope claim) is **at or before** the stored timestamp for any principal key it rides on:
112
+ A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's proof time) is **at or before** the stored timestamp for any principal key it rides on:
113
113
 
114
114
  | Key | Revokes | Written automatically on |
115
115
  |---|---|---|
@@ -122,6 +122,7 @@ A token is rejected when its mint timestamp (`iat`/`iatMs`, or `sct`/`sctMs` for
122
122
  Semantics worth knowing:
123
123
 
124
124
  - **Revoke-on-touch for scopes:** any update or delete of a conferring row stamps the revocation, without evaluating whether the change actually ended the relationship. A false positive just forces a cheap re-prove (`/scope/v1/enter` or a minting namespace route).
125
+ - **Scope proof time is per kind:** a token can carry several scope kinds proven at different instants, so each entry carries its own proof stamp (`sctMs`, `m<ms>`) and is compared against its own marker. Proving one kind never restamps the others — re-entering `event` cannot bring a revoked `location` claim back to life. Entries minted before the release that added the stamp carry none, and fall back to the token-level `sct`/`sctMs` until they expire (bounded by the carry-forward cap plus one TTL).
125
126
  - **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format version, not a magnitude the reader guesses at) and tokens carry millisecond companions (`iatMs` / `sctMs`) alongside the standards-compatible seconds claims, so a token minted a few milliseconds before the revocation is rejected — while one legitimately re-minted *after* it in that same second is still accepted. Tokens and markers written by v0.60.4 or earlier are handled **conservatively**: with no sub-second information on one side, the whole marker second is revoked. That over-revocation is bounded — the last old token expires within its TTL, and the last old marker within the entry lifetime. Like any rejected token it costs the caller a `401`, not a silent recovery: the bearer falls through unauthenticated (its cookie having been stripped, per the next bullet), and the client re-authenticates for a fresh token.
126
127
  - **Do not straddle the v0.61.0 upgrade.** A worker from **before** v0.61.0 reads `m<ms>` markers as `NaN` and treats them as *no revocation at all* — not as a corrupt entry. So rolling back across this release, or pointing two differently-versioned deploy targets at one shared KV namespace, means every revocation written by the new version is **silently unenforced** by the old one until the entry expires (`ENTRY_TTL_SECONDS`, ~19 minutes at default settings). Upgrade all targets sharing a namespace together; if you must roll back, treat outstanding bearer tokens as unrevoked for that window — lower `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
127
128
  - **Fails closed:** a missing binding, a failed read, or a corrupt entry means the token's revocation state is *unknown* — and an unknown bearer is not authenticated. The caller gets `503 AUTH_REVOCATION_UNAVAILABLE` (RFC 9457, retryable). Recovery is a **separate cookie-only request**: a request carrying `Authorization` has its cookie stripped before session auth, so within that one request there is nothing left to fall back to. Reads are never silently skipped, because the outage that hides a revocation is exactly the moment this check exists for.
@@ -94,7 +94,7 @@ Every optional top-level key the config accepts is listed below. You never have
94
94
  | Field | Type | Description |
95
95
  |-------|------|-------------|
96
96
  | `domain` | `string` | Primary custom domain (auto-inferred from `cms`/`account`/`api` domains if unset) — see [Domains](/configure/domains) |
97
- | `contract` | `{ version?: "v1" \| "v2" }` | Public API/auth contract version. Omit for the backward-compatible v1 default; select v2 for `/api/v2/*` and `/auth/v2/*` across generated routes, Better Auth, OpenAPI, MCP, and discovery. |
97
+ | `contract` | `{ version?: "v1" \| "v2", routes?: "v1" \| "v2" }` | Two independent axes. `version` selects SEMANTICS (default `"v2"`); `routes` selects the URL prefix (default `"v1"`). See [API Contract](/platform/api-contract#two-axes-semantics-and-routes). |
98
98
  | `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/configure/domains) |
99
99
  | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
100
100
  | `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `rules`, `tenants`, `permissions`, `arrows`) — see [Access](/define/authz-roles#centrally-defined-access-rules) and [Permissions](/define/permissions). `rules` = named gates (who + `record:` + firewall lanes under one name); `tenants` = named tenant anchors (`{ column, equals }`, referenced as `{ tenant: '<name>' }` in firewalls and `tenant: '<name>'` in auth-view includes). Root `authz` is the GLOBAL vocabulary level — names scoped to one concept belong in that concept's [feature area](/define/areas) (`_area.ts`), and root bodies may reference root-declared names only |
@@ -121,28 +121,28 @@ Every optional top-level key the config accepts is listed below. You never have
121
121
 
122
122
  ## Public contract version
123
123
 
124
- Quickback defaults to the existing v1 HTTP contract. New applications can opt
125
- into v2 explicitly:
124
+ Quickback runs the **v2 contract on `/api/v1` by default** — `version` and
125
+ `routes` are independent. Pin `version: "v1"` to opt out of v2 semantics; set
126
+ `routes: "v2"` to move the URLs:
126
127
 
127
128
  ```typescript
128
129
  export default defineConfig({
129
130
  name: "my-app",
130
131
  template: "hono",
131
- contract: { version: "v2" },
132
+ contract: { version: "v2", routes: "v2" },
132
133
  providers: cloudflare({}),
133
134
  });
134
135
  ```
135
136
 
136
- The selection is atomic: feature routes move to `/api/v2/*`, Better Auth moves
137
- to `/auth/v2/*`, and generated OpenAPI, MCP tool calls, OAuth discovery,
138
- `llms.txt`, schema/embeddings routes, and dedicated-domain `/v2/*` shortcuts
139
- use the same version. When CMS or Account is enabled, Quickback also bakes
140
- those paths into the SPA build and injects them at runtime, so CRUD, schema,
141
- live-view, and authentication requests use the selected contract. Quickback
142
- does not expose a mixed v1/v2 surface from one compiled Worker. Omitting
143
- `contract` remains byte-compatible with v1 projects.
137
+ `routes` is atomic across every surface: feature routes move to `/api/v2/*`,
138
+ Better Auth to `/auth/v2/*`, realtime to `/broadcast/v2`, and generated
139
+ OpenAPI, MCP tool calls, OAuth discovery, `llms.txt`, schema/embeddings routes,
140
+ and dedicated-domain shortcuts follow. When CMS or Account is enabled Quickback
141
+ bakes those paths into the SPA build and injects them at runtime. Quickback
142
+ does not expose a mixed v1/v2 URL surface from one compiled Worker.
144
143
 
145
- V2 also makes action input-schema fidelity a compile gate. The CLI must
144
+ Action input-schema fidelity is a compile gate on **every** contract version
145
+ since v0.63.0, not just v2. The CLI must
146
146
  successfully harvest `z.toJSONSchema(action.input)` for every authored action;
147
147
  partial or missing harvests fail with the exact action file keys, bundle or
148
148
  evaluation phase, and underlying local error. Dependencies are resolved from