@quickback-dev/cli 0.51.0 → 0.52.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 (91) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +34 -19
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +31 -21
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/lib/action-harvest.d.ts +35 -4
  9. package/dist/lib/action-harvest.d.ts.map +1 -1
  10. package/dist/lib/action-harvest.js +233 -50
  11. package/dist/lib/action-harvest.js.map +1 -1
  12. package/dist/lib/action-harvest.test.js +130 -2
  13. package/dist/lib/action-harvest.test.js.map +1 -1
  14. package/dist/lib/auth.d.ts +6 -0
  15. package/dist/lib/auth.d.ts.map +1 -1
  16. package/dist/lib/auth.js +18 -1
  17. package/dist/lib/auth.js.map +1 -1
  18. package/dist/lib/auth.test.d.ts +2 -0
  19. package/dist/lib/auth.test.d.ts.map +1 -0
  20. package/dist/lib/auth.test.js +19 -0
  21. package/dist/lib/auth.test.js.map +1 -0
  22. package/dist/lib/compile-next-steps.d.ts +4 -0
  23. package/dist/lib/compile-next-steps.d.ts.map +1 -0
  24. package/dist/lib/compile-next-steps.js +69 -0
  25. package/dist/lib/compile-next-steps.js.map +1 -0
  26. package/dist/lib/compile-next-steps.test.d.ts +2 -0
  27. package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
  28. package/dist/lib/compile-next-steps.test.js +76 -0
  29. package/dist/lib/compile-next-steps.test.js.map +1 -0
  30. package/dist/lib/file-loader.d.ts.map +1 -1
  31. package/dist/lib/file-loader.js +1 -0
  32. package/dist/lib/file-loader.js.map +1 -1
  33. package/dist/lib/file-writer.d.ts +1 -1
  34. package/dist/lib/file-writer.d.ts.map +1 -1
  35. package/dist/lib/file-writer.js +20 -5
  36. package/dist/lib/file-writer.js.map +1 -1
  37. package/dist/lib/file-writer.test.d.ts +2 -0
  38. package/dist/lib/file-writer.test.d.ts.map +1 -0
  39. package/dist/lib/file-writer.test.js +90 -0
  40. package/dist/lib/file-writer.test.js.map +1 -0
  41. package/dist/lib/shell.test.d.ts +2 -0
  42. package/dist/lib/shell.test.d.ts.map +1 -0
  43. package/dist/lib/shell.test.js +39 -0
  44. package/dist/lib/shell.test.js.map +1 -0
  45. package/dist/skill/docs/changelog.md +476 -2
  46. package/dist/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  47. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  48. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  49. package/dist/skill/docs/compiler/config/auth.md +17 -2
  50. package/dist/skill/docs/compiler/config/index.md +271 -12
  51. package/dist/skill/docs/compiler/config/output.md +49 -3
  52. package/dist/skill/docs/compiler/config/providers.md +12 -1
  53. package/dist/skill/docs/compiler/config/variables.md +5 -0
  54. package/dist/skill/docs/compiler/definitions/access.md +7 -0
  55. package/dist/skill/docs/compiler/definitions/actions.md +267 -9
  56. package/dist/skill/docs/compiler/definitions/bundles.md +69 -0
  57. package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
  58. package/dist/skill/docs/compiler/definitions/masking.md +2 -2
  59. package/dist/skill/docs/compiler/definitions/schema.md +12 -0
  60. package/dist/skill/docs/compiler/definitions/transitions.md +149 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  63. package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
  64. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  65. package/dist/skill/docs/stack/cms/schema-format.md +4 -2
  66. package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
  67. package/dist/skill/docs/stack/realtime/durable-objects.md +17 -4
  68. package/package.json +1 -1
  69. package/src/skill/docs/changelog.md +476 -2
  70. package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  71. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  72. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  73. package/src/skill/docs/compiler/config/auth.md +17 -2
  74. package/src/skill/docs/compiler/config/index.md +271 -12
  75. package/src/skill/docs/compiler/config/output.md +49 -3
  76. package/src/skill/docs/compiler/config/providers.md +12 -1
  77. package/src/skill/docs/compiler/config/variables.md +5 -0
  78. package/src/skill/docs/compiler/definitions/access.md +7 -0
  79. package/src/skill/docs/compiler/definitions/actions.md +267 -9
  80. package/src/skill/docs/compiler/definitions/bundles.md +69 -0
  81. package/src/skill/docs/compiler/definitions/firewall.md +6 -1
  82. package/src/skill/docs/compiler/definitions/masking.md +2 -2
  83. package/src/skill/docs/compiler/definitions/schema.md +12 -0
  84. package/src/skill/docs/compiler/definitions/transitions.md +149 -0
  85. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
  86. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  87. package/src/skill/docs/stack/account-ui/hooks.md +104 -1
  88. package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  89. package/src/skill/docs/stack/cms/schema-format.md +4 -2
  90. package/src/skill/docs/stack/cms/schema-registry.md +4 -2
  91. package/src/skill/docs/stack/realtime/durable-objects.md +17 -4
@@ -121,14 +121,27 @@ import { sendSMSWithSNS, smsTemplates, isValidE164 } from "@quickback-dev/better
121
121
  function getSNSConfig(env: CloudflareBindings | undefined): SNSConfig { /* ... */ }
122
122
 
123
123
  function createAuth(env, cf, executionCtx) {
124
- const fireAndForget = (p) => { /* waitUntil(p) */ };
124
+ const scheduleCredentialDelivery = (delivery) => {
125
+ const observed = delivery.catch(() => {
126
+ console.error(JSON.stringify({
127
+ level: "error",
128
+ event: "auth.credential_delivery_failed",
129
+ }));
130
+ throw new Error("Auth credential delivery failed");
131
+ });
132
+ if (executionCtx) {
133
+ executionCtx.waitUntil(observed);
134
+ return Promise.resolve();
135
+ }
136
+ return observed;
137
+ };
125
138
 
126
139
  return betterAuth({
127
140
  plugins: [
128
141
  phoneNumber({
129
142
  phoneNumberValidator: isValidE164,
130
143
  sendOTP: async ({ phoneNumber, code }) => {
131
- fireAndForget(sendSMSWithSNS(getSNSConfig(env), {
144
+ return scheduleCredentialDelivery(sendSMSWithSNS(getSNSConfig(env), {
132
145
  to: phoneNumber,
133
146
  message: smsTemplates.otp.message({ code, appName: ... }),
134
147
  }));
@@ -140,7 +153,11 @@ function createAuth(env, cf, executionCtx) {
140
153
  }
141
154
  ```
142
155
 
143
- That's the contract: callbacks are fire-and-forget via `executionCtx.waitUntil`, never `await`ed.
156
+ That's the contract: Workers callbacks return after `waitUntil` accepts an
157
+ observed, still-rejecting task, so provider latency stays out of the response.
158
+ Without an execution context, the callback returns the observed promise for the
159
+ caller to await. Failures are logged generically without provider error content
160
+ and are never swallowed.
144
161
 
145
162
  ## Sign-in flow
146
163
 
@@ -8,7 +8,6 @@ The top-level type:
8
8
 
9
9
  ```typescript
10
10
  interface SchemaRegistry {
11
- generatedAt: string;
12
11
  generatedBy: string;
13
12
  version: string;
14
13
  features: Record<string, string[]>;
@@ -22,7 +21,6 @@ interface SchemaRegistry {
22
21
 
23
22
  | Field | Description |
24
23
  |-------|-------------|
25
- | `generatedAt` | ISO 8601 timestamp of when the registry was generated |
26
24
  | `generatedBy` | Always `"quickback-compiler"` |
27
25
  | `version` | Compiler version string |
28
26
  | `features` | Map of feature name to array of source file names |
@@ -32,6 +30,10 @@ interface SchemaRegistry {
32
30
  | `pages` | Map of page slug to full page metadata |
33
31
  | `pagesByFeature` | Map of feature name to array of page slugs in that feature |
34
32
 
33
+ The registry deliberately omits wall-clock generation metadata. Every field is
34
+ derived from compiler inputs, so identical logical input produces
35
+ byte-identical `schema-registry.json` output across consecutive compiles.
36
+
35
37
  ## TableMeta
36
38
 
37
39
  Full metadata for a single table:
@@ -21,7 +21,6 @@ The top-level structure of `schema-registry.json`:
21
21
 
22
22
  ```json
23
23
  {
24
- "generatedAt": "2026-02-14T06:26:53.554Z",
25
24
  "generatedBy": "quickback-compiler",
26
25
  "version": "1.0.0",
27
26
  "features": { ... },
@@ -35,7 +34,6 @@ The top-level structure of `schema-registry.json`:
35
34
 
36
35
  | Field | Type | Description |
37
36
  |-------|------|-------------|
38
- | `generatedAt` | `string` | ISO timestamp of generation |
39
37
  | `generatedBy` | `string` | Always `"quickback-compiler"` |
40
38
  | `version` | `string` | Compiler version used |
41
39
  | `features` | `Record<string, string[]>` | Feature name to file list mapping |
@@ -45,6 +43,10 @@ The top-level structure of `schema-registry.json`:
45
43
  | `pages` | `Record<string, PageMeta>` | Page slug to full page metadata |
46
44
  | `pagesByFeature` | `Record<string, string[]>` | Feature name to page slug list |
47
45
 
46
+ The registry contains no wall-clock generation timestamp. Its bytes are fully
47
+ derived from the logical compiler input, so repeated compiles are stable for
48
+ artifact hashing, caches, and deployment diffs.
49
+
48
50
  ## TableMeta
49
51
 
50
52
  Each table entry contains everything the CMS needs to render its UI:
@@ -35,11 +35,21 @@ export default defineTable(applications, {
35
35
  onDelete: true, // Broadcast on DELETE (default: true)
36
36
  access: { roles: ["recruiter", "hiring-manager"] }, // Audience — MANDATORY, fail-closed
37
37
  fields: ["id", "candidateId", "stage"], // Fields to include (optional)
38
+ scopeKeyFrom: "events:{eventId}", // Sugar for scopeTable + scopeField (optional)
39
+ emitFromActions: true, // Custom-action writes auto-emit after commit (optional)
38
40
  },
39
41
  // ... guards, crud
40
42
  });
41
43
  ```
42
44
 
45
+ `scopeKeyFrom` routes broadcasts to a resource lane instead of the default
46
+ org room — the template form (`"events:{eventId}"`) names the prefix and the
47
+ row column in one string; a bare column name inherits the prefix from
48
+ `scopeTable` (or the project-level ws-ticket default). `emitFromActions`
49
+ extends the same broadcasts to writes made through the scoped `db` inside
50
+ custom record-bound and bulk actions — see the boundary table below. It
51
+ triggers the same mandatory-audience check auto-CRUD broadcasts have.
52
+
43
53
  When any table has realtime enabled, the compiler generates `src/lib/realtime.ts` with helper functions for sending notifications.
44
54
 
45
55
  At the project level, `providers.database.config.realtime` can stay boolean or become object-shaped when you need resource-scoped tickets. The mint gate accepts three authorization vocabularies via the discriminated `access` form — pick exactly one arm:
@@ -123,17 +133,20 @@ function can't be replicated by the Broadcaster, so those columns broadcast
123
133
  as `[REDACTED]` (fail closed). Tables that declare neither broadcast openly,
124
134
  as before.
125
135
 
126
- Everywhere else — action handlers, queue consumers, scheduled jobs, custom Hono routes — you broadcast manually. In action handlers on realtime-enabled projects, Quickback now injects a typed `realtime` helper directly into `execute(...)`; outside actions you still call `createRealtime(env)` yourself.
136
+ Everywhere else — action handlers, queue consumers, scheduled jobs, custom Hono routes — you broadcast manually **unless the table opts in to action emission** (see below). In action handlers on realtime-enabled projects, Quickback injects a typed `realtime` helper directly into `execute(...)`; outside actions you still call `createRealtime(env)` yourself.
127
137
 
128
138
  | Mutation site | Auto-broadcast? | Why |
129
139
  |---|---|---|
130
140
  | Generated CRUD route (`POST /`, `PATCH /:id`, `DELETE /:id`) | Yes | The compiler emits the call after the write returns. |
131
141
  | Generated batch route (`/batch/...`) | Yes | Same pattern, emitted per record. |
132
- | `scoped.insert/update/delete` inside an action handler | No — manual | Scoped-db is a query-shape wrapper (firewall + soft-delete WHERE injection). It deliberately has no side-effects so explicit handlers can write multiple records, conditionally roll back, etc. without surprise broadcasts. |
133
- | `unsafeDb` writes in actions (or any custom route) | No — manual | Same reasoning — `unsafeDb` is the un-wrapped escape hatch. |
142
+ | `db.insert/update/delete` inside a record-bound action, table declares `realtime.emitFromActions: true` | Yes — after commit | The scoped db records each write into a per-request capture collector (recording only — it never calls the transport itself); the route emits identical auto-CRUD frames after `execute` succeeds, via the after-commit effects machinery. |
143
+ | `db.insert/update/delete` inside an action handler (no `emitFromActions`) | No — manual | Scoped-db stays a query-shape wrapper (firewall + soft-delete WHERE injection) with no broadcast side-effects. |
144
+ | `unsafeDb` writes in actions (or any custom route) | No — manual | `unsafeDb` is the un-wrapped escape hatch — invisible to capture too. |
134
145
  | Queue consumers, cron jobs, webhook handlers | No — manual | These run outside the CRUD path entirely. |
135
146
 
136
- The rule of thumb: if your code calls `db.insert(...)` / `scoped.insert(...)` directly, you also call `realtime.insert(...)` directly on the next line. Otherwise the cross-tab live-update you wired up in the SPA won't fire.
147
+ The rule of thumb: opt the table into `realtime: { emitFromActions: true }` (or give the action an `emit:` block for the pre-bound `emitCrud(row, oldRow?)` helper) and the frames take care of themselves; otherwise, if your code calls `db.insert(...)` directly, you also call `realtime.insert(...)` directly on the next line.
148
+
149
+ Two capture caveats: inserts that skip `.returning()` emit the values as written (DB-default columns absent), and updates/deletes cost one extra pre-select on the same WHERE — it replaces the hand-written read every manual emit needed anyway. Capture covers the feature's own table on record-bound and bulk routes; standalone actions and cross-feature writes use `emit:`/`emitCrud` or the raw `realtime.*` API.
137
150
 
138
151
  ## Generated Helper
139
152
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.51.0",
3
+ "version": "0.52.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",
@@ -1,6 +1,480 @@
1
1
  # Changelog
2
2
 
3
- ## Unreleased
3
+ ## v0.52.0 — July 17, 2026
4
+
5
+ ### Five action primitives: afterCommit, realtime emit, transitions v2, refs, bundles
6
+
7
+ One release, five primitives that collapse the most-repeated hand-written
8
+ patterns in real Quickback projects (measured across a 349-action production
9
+ corpus). Every one is additive — existing projects compile unchanged, and
10
+ plain `{ field, fromTo, to|via }` transitions keep their emission
11
+ byte-identical.
12
+
13
+ - **`afterCommit` hooks + `effects.enqueue`** — named best-effort side
14
+ effects that run after `execute` returns. Each hook is independently
15
+ wrapped (failures log as `[<action>] afterCommit:<hook> failed`, never
16
+ touching the response), non-blocking hooks ride `executionCtx.waitUntil`,
17
+ `{ blocking: true }` awaits before responding, and everything skips when
18
+ `execute` throws or returns `dryRun: true`. The execute context also gains
19
+ `effects.enqueue(name, fn)` for mid-execute captures and `now` — one ISO
20
+ timestamp per invocation. Replaces the per-leg `try/catch + waitUntil`
21
+ idiom. See [After-commit hooks](/compiler/definitions/actions#after-commit-hooks).
22
+
23
+ - **Realtime emit for custom actions** — tables that lock auto-CRUD no
24
+ longer hand-roll frames. `realtime: { emitFromActions: true, scopeKeyFrom:
25
+ "events:{eventId}" }` makes scoped-db writes inside record-bound and bulk
26
+ actions emit auto-CRUD-byte-compatible frames after commit (masking +
27
+ audience applied at fanout; the fail-closed audience requirement extends to
28
+ action emission). Actions can also declare `emit:` for a pre-bound
29
+ `emitCrud(row, oldRow?)`. Updates/deletes pre-select old rows on the same
30
+ WHERE; raw `unsafeDb` writes stay invisible. See
31
+ [When auto-broadcast fires](/stack/realtime/durable-objects#when-auto-broadcast-fires-and-when-you-call-it-manually).
32
+
33
+ - **Transitions v2** — `transition` grows `guard` (equality / null / notNull
34
+ / `custom(record)`), `onIllegal { code, status, message }`, `idempotent:
35
+ "noop"`, and `stamp`/`clears` that ride a compiler-applied, TOCTOU-safe
36
+ UPDATE (guards fold into the WHERE; a lost race is 409
37
+ `ACCESS_TRANSITION_LOST`). With an applied write, `execute` becomes
38
+ optional. Table-level `transitions: { publish: { field, from, to, access } }`
39
+ *generates* the action files — including `undo:` inverses and `onEnter`
40
+ cascades — mounted exactly where hand-written files would be (explicit
41
+ files win, with a warning). The ten byte-identical publish/revert files in
42
+ the podcast fixture become two lines per entity. See
43
+ [Transitions](/compiler/definitions/transitions).
44
+
45
+ - **`refs` — scoped foreign-key inputs** — the "load the id, 404 if missing,
46
+ assert it belongs to this event" preamble becomes declarative. Loads run
47
+ through the scoped db (a cross-org id 404s by construction), batch into one
48
+ `Promise.all`, assert `matchScope` / cross-input `matchWith` parenthood, and
49
+ inject rows under their `as` names. Ref keys are validated against the
50
+ inline `z.object` input (with agreeing optionality) at compile time. See
51
+ [Refs](/compiler/definitions/actions#refs-scoped-foreign-key-inputs).
52
+
53
+ - **`defineBundle` — single-round-trip bootstrap reads** — declarative
54
+ `list()` slices with the firewall, the table's *real* mask functions, and
55
+ `{ data }` cache-seed envelopes; `custom()` escape-hatch sections; a SHA-1
56
+ ETag over `{ scopeSeed, userId, payload }` with the `ifNoneMatch →
57
+ notModified` short-circuit; and `Server-Timing`. Fail-closed: a bundle's
58
+ roles must be a subset of every list table's `read.access` roles — a bundle
59
+ can never widen read access. The digest ships as `sha1Hex` in `lib/etag`
60
+ so hand-written reads can delete their copies. See
61
+ [Bundles](/compiler/definitions/bundles).
62
+
63
+ Supporting changes: `ActionError` / `TransitionLostError` are re-exported
64
+ from the generated `.quickback/define-action` helpers (routes duck-type on
65
+ `error.name`, so project-local copies keep working); `sendQueueBatched` in
66
+ `lib/effects` chunks queue sends at the Cloudflare 100-message cap; and the
67
+ `$record.*` / `$ctx.*` substitution grammar used by `onEnter` and bundle
68
+ `where` is one strict allowlist, always parameterized — never interpolated
69
+ into SQL.
70
+
71
+ ### CLI device login fixed: /cli/authorize now claims the code before approving
72
+
73
+ Better Auth's `deviceAuthorization` plugin requires the verifying session to
74
+ claim a device code (`GET /device?user_code=…`) before it accepts an approve
75
+ or deny. The account SPA's `/cli/authorize` page posted the approval directly,
76
+ so every `quickback login` failed with *"Device code has not been claimed by
77
+ a verifying session."* The page now claims first, then approves — and surfaces
78
+ claim failures (expired or mistyped codes) with the server's message.
79
+ ### Generated builds no longer rewrite the auth schema
80
+
81
+ Generated Better Auth projects now run `tsc` directly from `npm run build`.
82
+ `quickback compile` already generates, qualifies, and envelopes
83
+ `src/auth/schema.ts`; invoking `auth:schema` again during every build rewrote
84
+ that compiler-owned artifact and made an otherwise clean release worktree
85
+ dirty. The explicit `auth:schema` diagnostic command remains available, while
86
+ normal build, Wrangler, and deployment preflight paths are source-read-only.
87
+ When recompiling an existing project, compiler-owned `package.json` script
88
+ names now converge to their current generated commands while unrelated custom
89
+ scripts are preserved. This upgrades projects whose previous generated
90
+ `build` script still invoked `auth:schema`.
91
+
92
+ ### Non-cross-tenant unsafe actions preserve delegated RLS claims
93
+
94
+ Generated Neon handlers now reserve `createServiceDb` for actions that
95
+ explicitly enable `unsafe.crossTenant`. An action that enables raw database
96
+ access with `crossTenant: false` keeps the request database, so organization
97
+ and delegated-principal claims survive into Hyperdrive transactions instead of
98
+ being cleared by the service-role preamble. True cross-tenant sysadmin actions
99
+ retain their audited RLS bypass.
100
+
101
+ Neon Hyperdrive guidance now also calls out Postgres' `SELECT … FOR UPDATE`
102
+ authorization rule: a locked row must pass both `SELECT` and `UPDATE` policies.
103
+ Delegated actions should use ordinary selects for read-only eligibility tables
104
+ and lock only mutable rows they are authorized to update. A PGlite regression
105
+ proves that ordinary delegated reads remain visible while the generated
106
+ restrictive update fence blocks an unauthorized row lock.
107
+
108
+ ### Atomic email-OTP auth routing no longer recurses on ordinary requests
109
+
110
+ The generated atomic email-OTP wrapper now captures and binds Better Auth's
111
+ original request handler before replacing the public `handler` property.
112
+ Session reads and every other non-atomic auth route therefore forward to Better
113
+ Auth exactly once instead of re-entering the wrapper until the Worker exhausts
114
+ its call stack. The exact email-OTP sign-in route retains its transactional
115
+ admission and rollback behavior.
116
+
117
+ ### Generated Better Auth CLI dependencies no longer retain vulnerable Lodash
118
+
119
+ Better Auth projects now emit a root npm override for `lodash@4.18.1`. This
120
+ keeps the supported stable `auth@1.6.x` CLI and its `better-auth` executable,
121
+ while lifting the CLI's dev-only Prisma parser chain off Lodash releases
122
+ affected by the 2026 code-injection and prototype-pollution advisories. Runtime
123
+ Better Auth packages and generated authentication behavior are unchanged.
124
+
125
+ The CLI now merges generated npm overrides explicitly when recompiling an
126
+ existing project: unrelated user overrides remain, while compiler-owned
127
+ security pins win a conflict. Recompile and reinstall dependencies to refresh
128
+ the project lockfile. `npm audit --omit=dev` remains the production dependency
129
+ view; upstream development-server advisories may still appear separately.
130
+
131
+ ### Postgres constraint replacements apply in dependency-safe order
132
+
133
+ Neon migration post-processing now orders both halves of a Drizzle constraint
134
+ replacement. A dependent foreign key is dropped before its referenced unique
135
+ or primary-key constraint, then the replacement key is added before the
136
+ foreign key that consumes it. This prevents Postgres `2BP01` failures when
137
+ Drizzle emits the parent key drop first, while preserving byte-identical output
138
+ for already-correct migrations and the relative order of unrelated statements.
139
+
140
+ ### Schema registry output is byte-reproducible
141
+
142
+ `schema-registry.json` no longer includes the wall-clock `generatedAt` field.
143
+ Its remaining metadata and schema content are derived entirely from compiler
144
+ inputs, so consecutive compiles of identical logical input now produce the
145
+ same registry bytes. This makes artifact hashes, caches, and deployment diffs
146
+ stable without timestamp normalization.
147
+
148
+ ### Generated auth and discovery surfaces now remain truthful and type-safe
149
+
150
+ Atomic email-OTP generation now imports and invokes
151
+ `before-email-otp-activate.ts` exactly once and preserves the transaction's
152
+ real Drizzle `select` capability in the hook context. Strict generated
153
+ TypeScript therefore accepts both the base Neon service database and its
154
+ interactive transaction without erasing the hook's read contract.
155
+
156
+ Contract-v2 projects that omit `auth.jwt` no longer advertise the disabled
157
+ Quickback JWT fast path in `llms.txt` or RFC 8414 metadata. Bearer-JWT guidance,
158
+ the fallback `/api/v2/token` endpoint, and JWT scopes are emitted only when the
159
+ corresponding JWT surface exists; real Better Auth OAuth-provider discovery is
160
+ unchanged.
161
+
162
+ Cloudflare Email callbacks now all enter the shared credential-delivery
163
+ scheduler exactly once. The scheduler anchors the observed rejection with
164
+ `waitUntil`, emits the metadata-only `auth.credential_delivery_failed` event,
165
+ and never leaks the provider error. Generated CRUD routes also keep delegated
166
+ principal and account authority disjoint: `?organizationId=` is rejected for a
167
+ delegated principal instead of synthesizing `activeOrgId` on its context. This
168
+ closes both the authority ambiguity and the generated `AppContext` union type
169
+ errors.
170
+
171
+ ### Email-OTP activation can be admitted atomically in the API layer
172
+
173
+ Contract-v2 Cloudflare projects using one Neon Hyperdrive database can opt the
174
+ exact Better Auth `POST /sign-in/email-otp` handler into an interactive
175
+ transaction with `atomicAuthRoutes: ["emailOtpSignIn"]`. The paired recognized
176
+ hook, `quickback/hooks/before-email-otp-activate.ts`, receives a proven dormant
177
+ user `{ userId, email, user }` plus transaction-bound `db` / full `schema` and
178
+ `authDb` / `authSchema` handles. Quickback owns only identity proof and atomic
179
+ orchestration; application admission, status, event, pass, and eligibility
180
+ rules remain authored in the project API hook.
181
+
182
+ The hook executes after OTP validation but in Better Auth's
183
+ `databaseHooks.user.update.before`, before the user update lock. This preserves
184
+ application-first lock ordering and avoids the user-to-application inversion a
185
+ session-create hook would introduce. Unknown-email signup must be disabled;
186
+ already-verified users do not rerun dormant activation.
187
+
188
+ The generated handler rebuilds Better Auth over the transaction handle, so OTP
189
+ consumption, project hook writes, the `emailVerified` update, and session insert
190
+ commit together. Admission denial, a non-ok response after activation starts,
191
+ and any 5xx response throw a private rollback sentinel. Expected policy denial
192
+ returns a generic 403. Operational rollback emits the metadata-only
193
+ `auth.atomic_email_otp_operational_rollback` event and returns a generic 503,
194
+ without exposing raw errors. Ordinary invalid-OTP 4xx responses still commit
195
+ Better Auth's attempt accounting, and the OTP-send route remains outside the
196
+ transaction. Unsupported contracts, runtimes, database modes,
197
+ missing/duplicated config, enabled signup,
198
+ and a hook/config mismatch now fail at compile time.
199
+
200
+ ### Neon migrations can declare cross-schema foreign keys
201
+
202
+ Neon projects can now declare fully qualified, single-column or composite
203
+ foreign keys under `compiler.migrations.foreignKeys`. Each entry names the
204
+ constraint, source and target schema/table/column tuples, and explicit
205
+ `onDelete` / `onUpdate` actions. The compiler rejects unsafe identifiers,
206
+ mismatched tuple arity, duplicate or ambiguous declarations, unknown keys,
207
+ and non-Neon providers before generating SQL.
208
+
209
+ Declared constraints are sorted deterministically and folded into Quickback's
210
+ content-addressed Postgres journal after the Drizzle schema migration. A new
211
+ constraint is added `NOT VALID` and then validated, so existing orphan rows
212
+ fail the migration; replay verifies an exact catalog match and rejects a
213
+ same-named constraint with different semantics. This surface enforces
214
+ relational integrity only—business rules remain in generated or authored API
215
+ actions, not database triggers.
216
+
217
+ ### Compile completion steps honor the Neon connection mode
218
+
219
+ The CLI's successful-compile footer now distinguishes Neon HTTP from
220
+ Hyperdrive. HTTP projects retain the direct `DATABASE_URL` Worker setup.
221
+ Hyperdrive projects show `DATABASE_MIGRATION_URL` only as a local or CI
222
+ migration input, point local development at the configured Hyperdrive
223
+ `localConnectionString`, and never recommend deploying `DATABASE_URL` as a
224
+ Worker secret.
225
+
226
+ Named Hyperdrive environments also show their configured Neon branches,
227
+ required-secret inventories, and explicit Wrangler `--env` targets. The footer
228
+ no longer suggests the unnamed `.env.neon` / `.dev.vars` workflow or a bare
229
+ deploy for an isolated `dev` / `prod` setup.
230
+
231
+ ### Cloudflare email delivery and named Neon targets fail visibly and deploy explicitly
232
+
233
+ Generated Cloudflare email code now uses the native Workers `SendEmail`,
234
+ `EmailAddress`, attachment, and `EmailSendResult` contracts. The Workers
235
+ builder keeps its camel-case fields and `{ email, name }` address shape, while
236
+ the REST transport retains its separate snake-case fields and `{ address,
237
+ name }` shape. Generated projects move to `@cloudflare/workers-types` v5 with
238
+ Wrangler 4.110 so the binding and result types agree without `any` casts.
239
+
240
+ Every Better Auth email callback now creates an observed delivery promise. On
241
+ Workers, the callback hands that still-rejecting promise to
242
+ `executionCtx.waitUntil(...)` and returns after the task is accepted; outside a
243
+ request lifecycle it returns the promise for the caller to await. Failures emit
244
+ only a structured generic event, never provider error content, and remain
245
+ rejected instead of being detached or swallowed. SES and SNS background sends
246
+ use the same lifecycle rule.
247
+
248
+ Neon Hyperdrive's generated postgres.js client now caps each request-scoped
249
+ pool at five connections. Named environments gain explicit `deploy:dev` and
250
+ `deploy:prod` package scripts (mapped to their configured Wrangler environment
251
+ names), while the unsafe bare `deploy` script remains absent and migrations
252
+ remain a separate target-owned step.
253
+
254
+ ### Contract v2 auth and Neon authority boundaries are fail-closed
255
+
256
+ Contract-v2 projects no longer emit Quickback's generic JWT mint endpoint,
257
+ JWT helper, middleware verification/mint fast-path, or related imports unless
258
+ the project explicitly declares `auth.jwt`. Contract v1 retains its existing
259
+ default for compatibility. Adding `auth.jwt: {}` to a v2 config opts back into
260
+ the custom Quickback JWT with its normal default settings.
261
+
262
+ Configured delegated authenticators now produce closed TypeScript unions in
263
+ both generated `AppContext` and Neon RLS context. Request contexts contain only
264
+ resolved principal variants; the compiler-internal credential-lookup variants
265
+ exist only in the database context. Delegated standalone actions do not require
266
+ Better Auth `activeOrgId` / `activeTeamId` before their declared principal
267
+ access tree runs, and their context cannot acquire account, organization, team,
268
+ membership, or scope authority.
269
+
270
+ On Cloudflare + Neon, the API-key organization membership lookup now runs with
271
+ request-scoped user/org RLS claims before it stamps verified organization and
272
+ role authority into `AppContext`. Generated security migrations also converge
273
+ direct privilege drift: the audit schema/table revoke all direct grants from
274
+ `PUBLIC`, the runtime, and admin before restoring their exact write-only/admin
275
+ sets, while the Drizzle journal schema/table/sequences and database `CREATE`
276
+ capability explicitly revoke `PUBLIC` and runtime access before granting the
277
+ migration role.
278
+
279
+ ### Standalone action routes preserve their exact authority context
280
+
281
+ Generated standalone routes now pass each action the context and scoped
282
+ database types inferred from that action's own `execute` signature. Account actions therefore receive a
283
+ required account identity, while `event_pass`, `event_delegate`, and other
284
+ delegated-principal actions retain their exact principal literal at the route
285
+ boundary. Relationship `loads` / `exposeAs` hydration is intersected with that
286
+ authority context, including required shared targets and optional distinct
287
+ multi-lane targets, instead of replacing it with the broad application
288
+ context.
289
+
290
+ The same boundary keeps ordinary request databases and temporary
291
+ service-role-backed scoped databases assignable to the generated Hyperdrive
292
+ action helper without widening the handler's schema-aware `db` type.
293
+
294
+ Generated principal-auth identity guards also emit explicit strict TypeScript
295
+ parameter and return types. Contract-v2 Cloudflare + Neon output no longer
296
+ fails `tsc` on implicit-`any` guard parameters.
297
+
298
+ ### Parameterized actions keep complete v2 schema harvests
299
+
300
+ The action-input harvest plan now converts Hono-style `:param` segments to the
301
+ OpenAPI `{param}` form for standalone actions and parameterized resource paths.
302
+ Previously the CLI could harvest every schema successfully, but the compiler
303
+ could apply only parameter-free actions because it looked up parameterized
304
+ operations under the wrong OpenAPI key. Contract v2 now counts and patches the
305
+ same canonical path emitted by OpenAPI and MCP.
306
+
307
+ Generated standalone-action routes also remove template-only trailing spaces
308
+ when optional audit blocks are absent, keeping regenerated source diffs clean.
309
+
310
+ ### Action-schema harvest uses the generated runtime dependency tree
311
+
312
+ The CLI now resolves action-harvest dependencies from the configured
313
+ `build.outputDir/node_modules` before unrelated ancestor installs. This fixes
314
+ isolated projects that keep authored definitions under `quickback/` and the
315
+ generated runtime under a sibling directory such as `src/`: their actions can
316
+ use the runtime's Zod 4 and Drizzle installation without adding workspace-root
317
+ symlinks. An older user-level or monorepo-level Zod can no longer shadow the
318
+ runtime's declared version during schema evaluation.
319
+
320
+ Schema-only evaluation also emits inert named table proxies for authored
321
+ Drizzle exports. Shared input/DTO modules may therefore construct top-level
322
+ selection objects such as `{ id: records.id }` without executing a database
323
+ operation or losing the action's Zod schema.
324
+
325
+ Harvest failures now retain the exact action key, failing phase (`bundle` or
326
+ `evaluation`), and bounded underlying error. Contract v2 includes those
327
+ per-action diagnostics in its fail-closed compile error; v1 retains its
328
+ best-effort static-schema fallback.
329
+
330
+ ### Contract v2 delegated principals and RLS-only action tables
331
+
332
+ Cloudflare + Neon Hyperdrive projects on `contract.version: "v2"` can now
333
+ declare framework-generic delegated authenticators under `auth.principals`.
334
+ Each named principal owns an exact, non-`Bearer` Authorization scheme, a
335
+ project hook that proves the credential and returns only `{ digest }`, and one
336
+ compiler-owned indexed lookup that resolves the actor, optional session/family,
337
+ string claims, and active status. The hook receives no database handle. Proof
338
+ hooks authored under `quickback/lib` are staged into generated `src/lib`, even
339
+ when no action imports them directly.
340
+
341
+ Delegated authority is structurally disjoint from Better Auth accounts:
342
+ `ctx.principal` is populated while user, organization, team, and membership
343
+ fields remain absent. Access arms may use `principals: [...]`; fields inside an
344
+ arm are ANDed and sibling arms are ORed. Generated action helpers preserve
345
+ that boundary in TypeScript, including the anonymous possibility of a
346
+ `PUBLIC` sibling arm. Mixed credential transport rejects Authorization plus an
347
+ API key or an actual Better Auth session cookie, while unrelated analytics
348
+ cookies do not create a false conflict. `Bearer` remains reserved for account
349
+ authentication.
350
+
351
+ Resources can also declare operation-specific `databaseAccess` policies for
352
+ authored actions and support tables. This is an RLS-only surface: it emits no
353
+ generic route or OpenAPI operation and is accepted only on Cloudflare + Neon
354
+ Hyperdrive. Every authorization path must contain a nonempty SQL-lowerable
355
+ record equality; unbounded principal/role leaves, any unbounded OR arm, empty
356
+ records, ambiguous mixed boolean nodes, app-only predicates, and unsupported
357
+ providers fail compilation. This keeps business logic in authored API actions
358
+ while Postgres independently enforces the same event/person or account/org row
359
+ boundary.
360
+
361
+ Principal claims use the same transaction-local Hyperdrive preamble as account
362
+ claims, with query caching disabled. Restrictive per-operation principal
363
+ fences prevent a public, exception, or legacy permissive policy from admitting
364
+ the wrong principal type. Credential lookup indexes and RLS journal entries are
365
+ content-addressed and converge when a table, digest column, or definition
366
+ changes; generated Postgres identifiers include collision-resistant hashes and
367
+ stay within the 63-byte limit. Each security migration also drops the complete
368
+ compiler-owned `databaseAccess` policy family before recreating the current
369
+ operations, so removing or moving an operation revokes the old permissive
370
+ policy instead of leaving it active. Record fields resolve through authoritative
371
+ Drizzle metadata to exact quoted physical identifiers, unknown fields fail the
372
+ compile, and DB-only pseudo-roles follow the same ADMIN/SYSADMIN/INTERNAL
373
+ contract as the application surface.
374
+
375
+ ### Action execute helpers preserve their typed boundary
376
+
377
+ Generated per-feature `defineAction` helpers no longer erase `services`, the
378
+ Hono request context, record predicates, or the action's return value to
379
+ `any`. Zod input and record inference remain intact, `whereRecord` and
380
+ `whereTransition` accept only the helper's bound table, and the existing D1 /
381
+ Neon Hyperdrive scoped `db` and interactive `tx` types now flow through the
382
+ same execute boundary. The returned value is inferred exactly; this does not
383
+ add a response schema, invalid-return rule, or new output contract.
384
+
385
+ HTTP/WebSocket Neon retains its intentionally dynamic `db`, and `AppContext`
386
+ retains its open index signature for runtime-hydrated namespace fields.
387
+
388
+ ### Neon Hyperdrive is now the only Worker database lane, including Better Auth
389
+
390
+ For `connectionMode: "hyperdrive"`, generated Better Auth code now uses the
391
+ same HYPERDRIVE-backed, service-role-scoped database handle as the rest of the
392
+ generated API. `DATABASE_URL` is no longer emitted or required as a Worker
393
+ secret in Hyperdrive mode; migration credentials remain inputs to the compiler
394
+ or CI environment. HTTP-mode Neon retains its existing `DATABASE_URL` runtime
395
+ contract.
396
+
397
+ ### Public contract v2 now compiles as one coherent API/auth surface
398
+
399
+ Projects may set `contract: { version: "v2" }` to select `/api/v2/*` feature
400
+ routes and `/auth/v2/*` Better Auth routes. The compiler now threads that
401
+ selection through generated route mounts, Better Auth configuration and
402
+ middleware, OpenAPI paths and server metadata, MCP internal tool calls, OAuth
403
+ discovery, `llms.txt`, schema/embeddings/system routes, live views, namespace
404
+ actions, and dedicated-domain `/v2/*` shortcuts. The option is no longer
405
+ fail-closed. Omitting `contract` or selecting `v1` preserves the existing v1
406
+ output.
407
+
408
+ Bundled CMS and Account clients now receive the selected API and auth base
409
+ paths through both their Vite build environment and the Worker-injected runtime
410
+ config. CMS CRUD, schema, sysadmin, and live-view requests and Account auth,
411
+ data, and live-view requests therefore stay on `/api/v2` and `/auth/v2` for a
412
+ v2 project instead of falling back to client-side v1 literals. V1 SPA config
413
+ retains its historical byte shape.
414
+
415
+ V2 compiles also require a complete client-side action input-schema harvest.
416
+ The current CLI reports the exact action files that failed to produce a JSON
417
+ Schema, and the compiler independently rejects missing, invalid, or partial
418
+ maps at the shared parse boundary used by both complete and validation-only
419
+ compiles. `POST /compile?complete=false` can no longer bypass the v2 gate. For
420
+ record actions with `bulkVariant: true`, the harvested schema now patches both
421
+ the single-record request body and the bulk operation's nested `input`; the
422
+ action is counted complete only when both OpenAPI targets exist. Harvest
423
+ planning also normalizes filename-based action bindings to the table's declared
424
+ name and resource path, so kebab-case filenames exporting snake/camel-case
425
+ tables are not silently omitted. V1 remains best-effort for backward
426
+ compatibility.
427
+
428
+ ### Complete, isolated Wrangler targets for named Neon environments
429
+
430
+ `providers.database.environments` now defines deployable Neon Hyperdrive
431
+ targets instead of emitting empty `[env.*]` shells. Because Wrangler does not
432
+ inherit vars or bindings into named environments, each target must explicitly
433
+ own its generated vars, required-secret contract, Hyperdrive and KV IDs,
434
+ rate-limit namespace IDs, and Cloudflare Email binding. The compiler rejects
435
+ missing overrides, shared stateful IDs, optional secret declarations, invalid
436
+ target semantics, and unsupported binding families rather than generating a
437
+ Worker that starts without part of its runtime.
438
+
439
+ The required-secret inventory is now centralized and includes generated
440
+ credentials as well as custom declarations: `BETTER_AUTH_SECRET`, a configured
441
+ `auth.jwt.secretEnv`, `ENCRYPTION_KEK` when envelope encryption is present, and
442
+ every `bindings.secrets` entry marked `required`. Generated Better Auth SES/SNS
443
+ credentials, AWS-backed anonymous-upgrade credentials, enabled social-provider
444
+ client id/secret pairs, and R2 presign credential env names are included as
445
+ well. Cloudflare social auth now reads those credentials from the Worker `env`
446
+ binding instead of relying on `process.env` compatibility behavior. Named
447
+ targets also reject every generated top-level custom-domain source — including
448
+ runtime routes, the primary/CMS/Account/Admin/Auth/API domains, and app domains
449
+ or aliases — until routes can be declared with explicit per-environment
450
+ ownership; top-level routes can no longer produce an ambiguous deployment
451
+ target.
452
+
453
+ Named targets are currently limited to Neon Hyperdrive with Better Auth.
454
+ External auth remains fail-closed until its service binding can be declared
455
+ independently for every named environment.
456
+
457
+ For named-environment projects, the base Worker has no deployable stateful
458
+ bindings, local development selects a named target, and that selected target
459
+ is always the required logical `dev` environment, which must own an explicit
460
+ development-only Hyperdrive `localConnectionString`. Quickback emits it only
461
+ in the selected named binding, rejects a top-level
462
+ override when named environments exist, and rejects local URLs on staging or
463
+ production targets; deployed targets continue to resolve the remote
464
+ Hyperdrive configuration by ID. The generated package omits the unsafe bare
465
+ deploy script. Existing projects that omit
466
+ `environments` keep byte-identical Wrangler output and the existing dev/deploy
467
+ scripts. See [Neon → Named Cloudflare deployment environments](/compiler/targets/hono-api/database/neon#named-cloudflare-deployment-environments).
468
+
469
+ ### Local compiler trust boundary and deterministic Drizzle commands
470
+
471
+ The supported Docker launcher now opts into unauthenticated local compilation
472
+ explicitly and publishes the compiler only on `127.0.0.1`; missing or unknown
473
+ compiler modes retain hosted authentication. The CLI recognizes only exact
474
+ loopback hostnames as local. Migration post-commands now use the configured
475
+ package manager's local binary execution form, with npm forced offline and its
476
+ implicit install prompt disabled, so a missing `drizzle-kit` fails clearly
477
+ instead of fetching an unpinned package.
4
478
 
5
479
  ### Action rate limits now emit — documented since the rate-limit pillar, wired now
6
480
 
@@ -40,7 +514,7 @@ The generated `auth:schema` script runs `npx better-auth generate`, but the
40
514
  lives in the npm package `auth` (the official Better Auth CLI; the team took
41
515
  over that name at 1.5.0, superseding the frozen `@better-auth/cli`). Generated
42
516
  projects now declare `auth` as a devDependency pinned to the runtime's minor
43
- line, so `npm run build` resolves the CLI locally instead of requiring a
517
+ line, so `npm run auth:schema` resolves the CLI locally instead of requiring a
44
518
  global install. The compiler image's global CLI is pinned to the same version,
45
519
  eliminating silent skew between the CLI on `latest` and the pinned runtime.
46
520