@quickback-dev/cli 0.63.0 → 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.
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.0";
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.
@@ -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
@@ -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
 
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.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",
@@ -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.
@@ -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
@@ -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