@quickback-dev/cli 0.63.0 → 0.64.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 (30) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/skill/docs/changelog/index.md +76 -4
  3. package/dist/skill/docs/configure/auth.md +7 -5
  4. package/dist/skill/docs/configure/index.md +17 -16
  5. package/dist/skill/docs/configure/providers.md +1 -1
  6. package/dist/skill/docs/define/changesets.md +8 -3
  7. package/dist/skill/docs/platform/api-contract/index.md +33 -20
  8. package/dist/skill/docs/platform/auth/jwt-optimization.md +4 -2
  9. package/dist/skill/docs/platform/realtime/durable-objects.md +1 -1
  10. package/dist/skill/docs/platform/realtime/index.md +1 -1
  11. package/dist/skill/docs/platform/realtime/live-views.md +1 -1
  12. package/dist/skill/docs/platform/realtime/named-invalidations.md +1 -1
  13. package/dist/skill/docs/platform/realtime/using-realtime.md +1 -1
  14. package/dist/skill/docs/tooling/output.md +3 -2
  15. package/dist/skill/docs/ui/admin/connecting.md +1 -1
  16. package/package.json +1 -1
  17. package/src/skill/docs/changelog/index.md +76 -4
  18. package/src/skill/docs/configure/auth.md +7 -5
  19. package/src/skill/docs/configure/index.md +17 -16
  20. package/src/skill/docs/configure/providers.md +1 -1
  21. package/src/skill/docs/define/changesets.md +8 -3
  22. package/src/skill/docs/platform/api-contract/index.md +33 -20
  23. package/src/skill/docs/platform/auth/jwt-optimization.md +4 -2
  24. package/src/skill/docs/platform/realtime/durable-objects.md +1 -1
  25. package/src/skill/docs/platform/realtime/index.md +1 -1
  26. package/src/skill/docs/platform/realtime/live-views.md +1 -1
  27. package/src/skill/docs/platform/realtime/named-invalidations.md +1 -1
  28. package/src/skill/docs/platform/realtime/using-realtime.md +1 -1
  29. package/src/skill/docs/tooling/output.md +3 -2
  30. package/src/skill/docs/ui/admin/connecting.md +1 -1
package/dist/index.js CHANGED
@@ -10,7 +10,7 @@
10
10
  */
11
11
  import pc from "picocolors";
12
12
  // Version injected at build time by scripts/inject-version.ts
13
- const CLI_VERSION = "0.63.0";
13
+ const CLI_VERSION = "0.64.1";
14
14
  function getPackageVersion() {
15
15
  return CLI_VERSION;
16
16
  }
@@ -8,6 +8,76 @@ 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
+ ## 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
+
11
81
  ## v0.63.0 — August 14, 2026
12
82
 
13
83
  ### Action input schemas now fail the compile instead of degrading
@@ -39,12 +109,14 @@ total lost `required`, with sampled paths.
39
109
  ### `contract.version` default flips to v2 in v0.64.0
40
110
 
41
111
  An unset `contract.version` resolves to `'v1'` today. That default becomes
42
- `'v2'` in **v0.64.0**, which moves `/api/v1` → `/api/v2` (plus `/auth` and
43
- `/broadcast`), switches realtime frames to CloudEvents 1.0 envelopes, drops the
44
- legacy `X-Webhook-*` signing headers, and disables the Quickback HMAC-JWT lane
45
- unless `auth.jwt` is declared. See the
112
+ `'v2'` in **v0.64.0**. See the
46
113
  [contract matrix](/platform/api-contract#contract-version-matrix).
47
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
+
48
120
  Every compile that leaves `contract.version` unset now warns. Pin
49
121
  `contract: { version: "v1" }` to keep the current wire, or set `"v2"` to migrate
50
122
  now.
@@ -24,12 +24,14 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
24
24
 
25
25
  Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
26
26
 
27
- > **Contract v2 is opt-in**
27
+ > **This JWT surface is opt-in by default**
28
28
  >
29
- > On `contract: { version: "v2" }`, Quickback emits this custom JWT surface only
30
- > when `auth.jwt` is present. If it is omitted, generated output has no generic
31
- > `/api/v2/token` endpoint, `src/lib/jwt.ts`, JWT middleware verify/mint fast-path,
32
- > or Quickback JWT imports. Generated `llms.txt` and RFC 8414 discovery metadata
29
+ > Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
30
+ > JWT surface only when `auth.jwt` is present. If it is omitted, generated output
31
+ > has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
32
+ > fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
33
+ > the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
34
+ > JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
33
35
  > also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
34
36
  > exist. Better Auth cookie and signed session-token bearer authentication remain
35
37
  > available.
@@ -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
@@ -499,12 +499,13 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
499
499
 
500
500
  When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
501
501
 
502
- - `/api/v1/*` and `/auth/v1/*` for the default contract, or `/api/v2/*` and
503
- `/auth/v2/*` when `contract.version` is `"v2"`
502
+ - `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
503
+ when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
504
+ not move these)
504
505
  - `/storage/*` — R2 file storage
505
506
  - `/health`, `/openapi.json` — monitoring/discovery
506
507
  - `/account/*`, `/cms/*` — bundled SPAs (when enabled)
507
- - `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.version: 'v2'`), `/mcp` (MCP), etc.
508
+ - `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.routes: 'v2'`), `/mcp` (MCP), etc.
508
509
 
509
510
  The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
510
511
 
@@ -215,7 +215,7 @@ providers: {
215
215
  }
216
216
  ```
217
217
 
218
- > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.version: "v2"`.
218
+ > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
219
219
 
220
220
  `wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
221
221
 
@@ -70,14 +70,19 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
70
70
  One blessed path — **RFC 5789 media-type dispatch** on the routes you already
71
71
  have. No subpath.
72
72
 
73
- - `PATCH /api/v2/<resource>/:id` with
73
+ Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
74
+ **semantics** feature and v2 is the default, so they are available without
75
+ moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
76
+ to `"v2"` only if you also want the `/api/v2` prefix.
77
+
78
+ - `PATCH /api/v1/<resource>/:id` with
74
79
  `Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
75
80
  to an existing root. Plain `application/json` keeps the flat-column PATCH.
76
- - `POST /api/v2/<resource>` with the same media type — create the root and its
81
+ - `POST /api/v1/<resource>` with the same media type — create the root and its
77
82
  children in one changeset.
78
83
 
79
84
  ```jsonc
80
- // PATCH /api/v2/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
85
+ // PATCH /api/v1/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
81
86
  {
82
87
  "patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
83
88
  "tasks": {
@@ -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,28 +112,39 @@ export default defineAction({
111
112
  });
112
113
  ```
113
114
 
114
- ## The default becomes v2 in v0.64.0
115
+ ## Two axes: semantics and routes
115
116
 
116
- `contract.version` resolves to `'v1'` when unset. That default becomes `'v2'`
117
- in Quickback **v0.64.0**. Every project without an explicit `contract.version`
118
- moves the entire matrix below on its next compile after that release.
117
+ `contract` has two independent keys, and conflating them is the most common
118
+ mistake:
119
119
 
120
- Pin the current wire:
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.
121
128
 
129
+ {/* doc-compile: skip — config fragment, not a compilable project */}
122
130
  ```typescript
123
- {/* doc-compile: skip — config fragment */}
124
- contract: { version: "v1" }
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"
125
134
  ```
126
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
+
127
140
  **Pinning your CLI version does not pin the contract.** The default lives in the
128
- compiler, which is a hosted service — an older CLI inherits the flip too. The
129
- config key is the only pin. v0.63.0 warns on every compile that leaves
130
- `contract.version` unset.
141
+ compiler, which is a hosted service — an older CLI inherits it too. The config
142
+ key is the only pin.
131
143
 
132
144
  ## Contract version matrix
133
145
 
134
- Flipping `contract.version` moves the **entire** contract at once — plan the
135
- client migration as one move:
146
+ `version` moves everything in this table except the three base paths, which
147
+ follow `routes`:
136
148
 
137
149
  | Surface | v1 (pinned) | v2 (flagship) |
138
150
  |---|---|---|
@@ -148,10 +160,11 @@ client migration as one move:
148
160
  | `fields[<fk>]=` unknown names | n/a | **400** |
149
161
  | Action input schemas | complete client-side harvest **required** (since v0.63.0) | complete client-side harvest **required** |
150
162
 
151
- Sequencing a migration: ship clients that speak the v2 paths, CloudEvents
152
- frames, and session-first auth (or declare `auth.jwt`); confirm webhook
153
- consumers validate the `webhook-*` headers; then flip the switch. Until then
154
- 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.
155
168
 
156
169
  ## Machine-readable contract
157
170
 
@@ -49,9 +49,11 @@ auth: {
49
49
  },
50
50
  ```
51
51
 
52
- > **Contract v2 makes this surface opt-in**
52
+ > **This surface is opt-in by default**
53
53
  >
54
- > On `contract: { version: "v2" }`, the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint, no `src/lib/jwt.ts`, and no JWT fast-path — cookie and signed session-token bearer auth still work. Contract v1 always emits it. See [Auth & JWT config](/configure/auth).
54
+ > Contract v2 is the default since v0.64.0, and on it the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
55
+ >
56
+ > `src/lib/jwt.ts` is still emitted when the project declares [`authz.scopes`](/define/scopes): scope tokens are signed JWTs, so the helper is required for minting and verifying them even with no credential lane.
55
57
 
56
58
 
57
59
  ---
@@ -79,7 +79,7 @@ providers: {
79
79
  }
80
80
  ```
81
81
 
82
- That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.version`, so `/broadcast/v2/ws-ticket` on contract-v2 projects) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
82
+ That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.routes`, so `/broadcast/v2/ws-ticket` when that is `"v2"`) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
83
83
 
84
84
  ### Namespace-backed tickets (per-matched-lane)
85
85
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
4
4
 
5
- - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.version` — contract-v2 projects mount the same surface at `/broadcast/v2` (no hidden v1 alias). Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
5
+ - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
6
6
  - **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
7
7
 
8
8
  Both share the same auth model and ride on the same compiled worker; they solve different problems.
@@ -157,7 +157,7 @@ function PersonDetail({ personId }: { personId: string }) {
157
157
  Under the hood `useView` uses a **subscribe-then-snapshot** flow so no change
158
158
  slips through the gap between reading the surface and the socket going live:
159
159
 
160
- 1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` on contract-v2 projects — with
160
+ 1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` when `contract.routes` is `"v2"` — with
161
161
  `{ view, rootId }`) — gated by exactly the same `read.access` + firewall
162
162
  checks as the read endpoint — and opens a WebSocket scoped to
163
163
  `view:<view>:<rootId>`.
@@ -125,7 +125,7 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
125
125
 
126
126
  ## The wire frame
127
127
 
128
- Clients receive a broadcast frame on `/broadcast/v{n}` (the version tracks `contract.version`):
128
+ Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
129
129
 
130
130
  ```jsonc
131
131
  {
@@ -8,7 +8,7 @@ Open a WebSocket connection to the realtime worker:
8
8
 
9
9
  ```typescript
10
10
  const ws = new WebSocket("wss://api.yourdomain.com/broadcast/v1/websocket");
11
- // Note: /broadcast/v1 tracks contract.version — use /broadcast/v2 on contract-v2 projects.
11
+ // Note: /broadcast/v1 tracks contract.routes — use /broadcast/v2 when that is "v2".
12
12
  ```
13
13
 
14
14
  ## Authentication
@@ -377,8 +377,9 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
377
377
  | `POST /:id/{action}` | Record-based actions defined |
378
378
  | `POST /{action}` | Standalone actions defined |
379
379
 
380
- Routes are mounted under `/api/v1/{feature}` for the default contract or
381
- `/api/v2/{feature}` when `contract: { version: "v2" }` is selected.
380
+ Routes are mounted under `/api/v1/{feature}` by default, or
381
+ `/api/v2/{feature}` when `contract: { routes: "v2" }` is set. `contract.version`
382
+ selects semantics and leaves these paths alone.
382
383
 
383
384
  ## Migrations
384
385
 
@@ -105,7 +105,7 @@ interface ListResult {
105
105
  The client is constructed once from the resolved `apiUrl` and provided via React
106
106
  context (`ApiClientContext`), available throughout the component tree. It reads
107
107
  the Better Auth session cookie and calls the standard REST endpoints
108
- (`/api/v1/{table}`, or `/api/v2/…` on contract-v2 projects).
108
+ (`/api/v1/{table}`, or `/api/v2/…` when `contract.routes` is `"v2"`).
109
109
 
110
110
  ## Embedded Mode (Recommended)
111
111
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.63.0",
3
+ "version": "0.64.1",
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",
@@ -8,6 +8,76 @@ 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
+ ## 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
+
11
81
  ## v0.63.0 — August 14, 2026
12
82
 
13
83
  ### Action input schemas now fail the compile instead of degrading
@@ -39,12 +109,14 @@ total lost `required`, with sampled paths.
39
109
  ### `contract.version` default flips to v2 in v0.64.0
40
110
 
41
111
  An unset `contract.version` resolves to `'v1'` today. That default becomes
42
- `'v2'` in **v0.64.0**, which moves `/api/v1` → `/api/v2` (plus `/auth` and
43
- `/broadcast`), switches realtime frames to CloudEvents 1.0 envelopes, drops the
44
- legacy `X-Webhook-*` signing headers, and disables the Quickback HMAC-JWT lane
45
- unless `auth.jwt` is declared. See the
112
+ `'v2'` in **v0.64.0**. See the
46
113
  [contract matrix](/platform/api-contract#contract-version-matrix).
47
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
+
48
120
  Every compile that leaves `contract.version` unset now warns. Pin
49
121
  `contract: { version: "v1" }` to keep the current wire, or set `"v2"` to migrate
50
122
  now.
@@ -24,12 +24,14 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
24
24
 
25
25
  Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
26
26
 
27
- > **Contract v2 is opt-in**
27
+ > **This JWT surface is opt-in by default**
28
28
  >
29
- > On `contract: { version: "v2" }`, Quickback emits this custom JWT surface only
30
- > when `auth.jwt` is present. If it is omitted, generated output has no generic
31
- > `/api/v2/token` endpoint, `src/lib/jwt.ts`, JWT middleware verify/mint fast-path,
32
- > or Quickback JWT imports. Generated `llms.txt` and RFC 8414 discovery metadata
29
+ > Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
30
+ > JWT surface only when `auth.jwt` is present. If it is omitted, generated output
31
+ > has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
32
+ > fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
33
+ > the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
34
+ > JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
33
35
  > also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
34
36
  > exist. Better Auth cookie and signed session-token bearer authentication remain
35
37
  > available.
@@ -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
@@ -499,12 +499,13 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
499
499
 
500
500
  When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
501
501
 
502
- - `/api/v1/*` and `/auth/v1/*` for the default contract, or `/api/v2/*` and
503
- `/auth/v2/*` when `contract.version` is `"v2"`
502
+ - `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
503
+ when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
504
+ not move these)
504
505
  - `/storage/*` — R2 file storage
505
506
  - `/health`, `/openapi.json` — monitoring/discovery
506
507
  - `/account/*`, `/cms/*` — bundled SPAs (when enabled)
507
- - `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.version: 'v2'`), `/mcp` (MCP), etc.
508
+ - `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.routes: 'v2'`), `/mcp` (MCP), etc.
508
509
 
509
510
  The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
510
511
 
@@ -215,7 +215,7 @@ providers: {
215
215
  }
216
216
  ```
217
217
 
218
- > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.version: "v2"`.
218
+ > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
219
219
 
220
220
  `wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
221
221
 
@@ -70,14 +70,19 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
70
70
  One blessed path — **RFC 5789 media-type dispatch** on the routes you already
71
71
  have. No subpath.
72
72
 
73
- - `PATCH /api/v2/<resource>/:id` with
73
+ Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
74
+ **semantics** feature and v2 is the default, so they are available without
75
+ moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
76
+ to `"v2"` only if you also want the `/api/v2` prefix.
77
+
78
+ - `PATCH /api/v1/<resource>/:id` with
74
79
  `Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
75
80
  to an existing root. Plain `application/json` keeps the flat-column PATCH.
76
- - `POST /api/v2/<resource>` with the same media type — create the root and its
81
+ - `POST /api/v1/<resource>` with the same media type — create the root and its
77
82
  children in one changeset.
78
83
 
79
84
  ```jsonc
80
- // PATCH /api/v2/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
85
+ // PATCH /api/v1/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
81
86
  {
82
87
  "patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
83
88
  "tasks": {
@@ -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,28 +112,39 @@ export default defineAction({
111
112
  });
112
113
  ```
113
114
 
114
- ## The default becomes v2 in v0.64.0
115
+ ## Two axes: semantics and routes
115
116
 
116
- `contract.version` resolves to `'v1'` when unset. That default becomes `'v2'`
117
- in Quickback **v0.64.0**. Every project without an explicit `contract.version`
118
- moves the entire matrix below on its next compile after that release.
117
+ `contract` has two independent keys, and conflating them is the most common
118
+ mistake:
119
119
 
120
- Pin the current wire:
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.
121
128
 
129
+ {/* doc-compile: skip — config fragment, not a compilable project */}
122
130
  ```typescript
123
- {/* doc-compile: skip — config fragment */}
124
- contract: { version: "v1" }
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"
125
134
  ```
126
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
+
127
140
  **Pinning your CLI version does not pin the contract.** The default lives in the
128
- compiler, which is a hosted service — an older CLI inherits the flip too. The
129
- config key is the only pin. v0.63.0 warns on every compile that leaves
130
- `contract.version` unset.
141
+ compiler, which is a hosted service — an older CLI inherits it too. The config
142
+ key is the only pin.
131
143
 
132
144
  ## Contract version matrix
133
145
 
134
- Flipping `contract.version` moves the **entire** contract at once — plan the
135
- client migration as one move:
146
+ `version` moves everything in this table except the three base paths, which
147
+ follow `routes`:
136
148
 
137
149
  | Surface | v1 (pinned) | v2 (flagship) |
138
150
  |---|---|---|
@@ -148,10 +160,11 @@ client migration as one move:
148
160
  | `fields[<fk>]=` unknown names | n/a | **400** |
149
161
  | Action input schemas | complete client-side harvest **required** (since v0.63.0) | complete client-side harvest **required** |
150
162
 
151
- Sequencing a migration: ship clients that speak the v2 paths, CloudEvents
152
- frames, and session-first auth (or declare `auth.jwt`); confirm webhook
153
- consumers validate the `webhook-*` headers; then flip the switch. Until then
154
- 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.
155
168
 
156
169
  ## Machine-readable contract
157
170
 
@@ -49,9 +49,11 @@ auth: {
49
49
  },
50
50
  ```
51
51
 
52
- > **Contract v2 makes this surface opt-in**
52
+ > **This surface is opt-in by default**
53
53
  >
54
- > On `contract: { version: "v2" }`, the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint, no `src/lib/jwt.ts`, and no JWT fast-path — cookie and signed session-token bearer auth still work. Contract v1 always emits it. See [Auth & JWT config](/configure/auth).
54
+ > Contract v2 is the default since v0.64.0, and on it the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
55
+ >
56
+ > `src/lib/jwt.ts` is still emitted when the project declares [`authz.scopes`](/define/scopes): scope tokens are signed JWTs, so the helper is required for minting and verifying them even with no credential lane.
55
57
 
56
58
 
57
59
  ---
@@ -79,7 +79,7 @@ providers: {
79
79
  }
80
80
  ```
81
81
 
82
- That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.version`, so `/broadcast/v2/ws-ticket` on contract-v2 projects) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
82
+ That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.routes`, so `/broadcast/v2/ws-ticket` when that is `"v2"`) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
83
83
 
84
84
  ### Namespace-backed tickets (per-matched-lane)
85
85
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
4
4
 
5
- - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.version` — contract-v2 projects mount the same surface at `/broadcast/v2` (no hidden v1 alias). Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
5
+ - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
6
6
  - **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
7
7
 
8
8
  Both share the same auth model and ride on the same compiled worker; they solve different problems.
@@ -157,7 +157,7 @@ function PersonDetail({ personId }: { personId: string }) {
157
157
  Under the hood `useView` uses a **subscribe-then-snapshot** flow so no change
158
158
  slips through the gap between reading the surface and the socket going live:
159
159
 
160
- 1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` on contract-v2 projects — with
160
+ 1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` when `contract.routes` is `"v2"` — with
161
161
  `{ view, rootId }`) — gated by exactly the same `read.access` + firewall
162
162
  checks as the read endpoint — and opens a WebSocket scoped to
163
163
  `view:<view>:<rootId>`.
@@ -125,7 +125,7 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
125
125
 
126
126
  ## The wire frame
127
127
 
128
- Clients receive a broadcast frame on `/broadcast/v{n}` (the version tracks `contract.version`):
128
+ Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
129
129
 
130
130
  ```jsonc
131
131
  {
@@ -8,7 +8,7 @@ Open a WebSocket connection to the realtime worker:
8
8
 
9
9
  ```typescript
10
10
  const ws = new WebSocket("wss://api.yourdomain.com/broadcast/v1/websocket");
11
- // Note: /broadcast/v1 tracks contract.version — use /broadcast/v2 on contract-v2 projects.
11
+ // Note: /broadcast/v1 tracks contract.routes — use /broadcast/v2 when that is "v2".
12
12
  ```
13
13
 
14
14
  ## Authentication
@@ -377,8 +377,9 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
377
377
  | `POST /:id/{action}` | Record-based actions defined |
378
378
  | `POST /{action}` | Standalone actions defined |
379
379
 
380
- Routes are mounted under `/api/v1/{feature}` for the default contract or
381
- `/api/v2/{feature}` when `contract: { version: "v2" }` is selected.
380
+ Routes are mounted under `/api/v1/{feature}` by default, or
381
+ `/api/v2/{feature}` when `contract: { routes: "v2" }` is set. `contract.version`
382
+ selects semantics and leaves these paths alone.
382
383
 
383
384
  ## Migrations
384
385
 
@@ -105,7 +105,7 @@ interface ListResult {
105
105
  The client is constructed once from the resolved `apiUrl` and provided via React
106
106
  context (`ApiClientContext`), available throughout the component tree. It reads
107
107
  the Better Auth session cookie and calls the standard REST endpoints
108
- (`/api/v1/{table}`, or `/api/v2/…` on contract-v2 projects).
108
+ (`/api/v1/{table}`, or `/api/v2/…` when `contract.routes` is `"v2"`).
109
109
 
110
110
  ## Embedded Mode (Recommended)
111
111