@quickback-dev/cli 0.70.45 → 0.72.2

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 (228) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +10 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/deploy.d.ts.map +1 -1
  5. package/dist/commands/deploy.js +7 -1
  6. package/dist/commands/deploy.js.map +1 -1
  7. package/dist/commands/mcp.d.ts.map +1 -1
  8. package/dist/commands/mcp.js +6 -5
  9. package/dist/commands/mcp.js.map +1 -1
  10. package/dist/index.js +1 -1
  11. package/dist/index.js.map +1 -1
  12. package/dist/lib/access-manifest-diff.d.ts +6 -0
  13. package/dist/lib/access-manifest-diff.d.ts.map +1 -1
  14. package/dist/lib/access-manifest-diff.js +10 -0
  15. package/dist/lib/access-manifest-diff.js.map +1 -1
  16. package/dist/lib/action-harvest.d.ts.map +1 -1
  17. package/dist/lib/action-harvest.js +36 -0
  18. package/dist/lib/action-harvest.js.map +1 -1
  19. package/dist/lib/api-client.d.ts +8 -0
  20. package/dist/lib/api-client.d.ts.map +1 -1
  21. package/dist/lib/api-client.js.map +1 -1
  22. package/dist/lib/deployment-target.d.ts +13 -0
  23. package/dist/lib/deployment-target.d.ts.map +1 -1
  24. package/dist/lib/deployment-target.js +4 -0
  25. package/dist/lib/deployment-target.js.map +1 -1
  26. package/dist/lib/file-loader.d.ts +22 -0
  27. package/dist/lib/file-loader.d.ts.map +1 -1
  28. package/dist/lib/file-loader.js +80 -18
  29. package/dist/lib/file-loader.js.map +1 -1
  30. package/dist/lib/file-writer.js +9 -0
  31. package/dist/lib/file-writer.js.map +1 -1
  32. package/dist/lib/harness.d.ts +10 -0
  33. package/dist/lib/harness.d.ts.map +1 -1
  34. package/dist/lib/harness.js +31 -0
  35. package/dist/lib/harness.js.map +1 -1
  36. package/dist/lib/migrations/executor.js +5 -1
  37. package/dist/lib/migrations/executor.js.map +1 -1
  38. package/dist/lib/migrations/plan.js +3 -0
  39. package/dist/lib/migrations/plan.js.map +1 -1
  40. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
  41. package/dist/lib/migrations/postprocessors/index.js +23 -2
  42. package/dist/lib/migrations/postprocessors/index.js.map +1 -1
  43. package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
  44. package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
  45. package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
  46. package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
  47. package/dist/lib/migrations/prior-state.d.ts +13 -1
  48. package/dist/lib/migrations/prior-state.d.ts.map +1 -1
  49. package/dist/lib/migrations/prior-state.js +33 -2
  50. package/dist/lib/migrations/prior-state.js.map +1 -1
  51. package/dist/lib/migrations/types.d.ts +2 -2
  52. package/dist/lib/migrations/types.d.ts.map +1 -1
  53. package/dist/lib/migrations/types.js +3 -0
  54. package/dist/lib/migrations/types.js.map +1 -1
  55. package/dist/lib/wrangler-resources.d.ts +14 -1
  56. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  57. package/dist/lib/wrangler-resources.js +29 -7
  58. package/dist/lib/wrangler-resources.js.map +1 -1
  59. package/dist/skill/docs/api/actions.md +73 -2
  60. package/dist/skill/docs/api/batch-operations.md +2 -0
  61. package/dist/skill/docs/api/caching.md +2 -2
  62. package/dist/skill/docs/api/crud.md +13 -0
  63. package/dist/skill/docs/api/errors.md +111 -10
  64. package/dist/skill/docs/api/index.md +24 -0
  65. package/dist/skill/docs/api/openapi.md +8 -0
  66. package/dist/skill/docs/api/query-params.md +6 -0
  67. package/dist/skill/docs/configure/agents.md +73 -1
  68. package/dist/skill/docs/configure/auth.md +7 -1
  69. package/dist/skill/docs/configure/bindings.md +55 -0
  70. package/dist/skill/docs/configure/cloudflare-access.md +191 -0
  71. package/dist/skill/docs/configure/domains.md +1 -1
  72. package/dist/skill/docs/configure/index.md +4 -2
  73. package/dist/skill/docs/configure/providers.md +2 -1
  74. package/dist/skill/docs/configure/tenancy.md +3 -0
  75. package/dist/skill/docs/configure/tenant-databases.md +2407 -0
  76. package/dist/skill/docs/define/access.md +33 -1
  77. package/dist/skill/docs/define/actions/defining.md +118 -1
  78. package/dist/skill/docs/define/actions/scoped-db.md +32 -8
  79. package/dist/skill/docs/define/areas.md +145 -2
  80. package/dist/skill/docs/define/diagnostics.md +160 -21
  81. package/dist/skill/docs/define/encryption.md +13 -2
  82. package/dist/skill/docs/define/fga.md +320 -42
  83. package/dist/skill/docs/define/firewall.md +4 -0
  84. package/dist/skill/docs/define/index.md +1 -0
  85. package/dist/skill/docs/define/read.md +39 -0
  86. package/dist/skill/docs/define/relationships.md +30 -12
  87. package/dist/skill/docs/define/schema.md +2 -0
  88. package/dist/skill/docs/define/scopes.md +393 -9
  89. package/dist/skill/docs/define/sealed-protocol.md +67 -12
  90. package/dist/skill/docs/define/transitions.md +4 -1
  91. package/dist/skill/docs/define/triggers.md +55 -1
  92. package/dist/skill/docs/platform/api-contract/index.md +4 -2
  93. package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
  94. package/dist/skill/docs/platform/auth/using-auth.md +1 -1
  95. package/dist/skill/docs/platform/database/d1.md +112 -3
  96. package/dist/skill/docs/platform/database/data-migrations.md +3 -1
  97. package/dist/skill/docs/platform/database/neon.md +10 -2
  98. package/dist/skill/docs/platform/queues/handlers.md +48 -16
  99. package/dist/skill/docs/platform/queues/using-queues.md +16 -0
  100. package/dist/skill/docs/platform/realtime/durable-objects.md +285 -17
  101. package/dist/skill/docs/platform/realtime/index.md +9 -6
  102. package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
  103. package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
  104. package/dist/skill/docs/platform/schedules/index.md +1 -1
  105. package/dist/skill/docs/platform/storage/r2.md +10 -1
  106. package/dist/skill/docs/platform/storage/using-r2.md +42 -1
  107. package/dist/skill/docs/tooling/output.md +9 -2
  108. package/dist/skill/docs/ui/account/features/admin.md +5 -3
  109. package/dist/skill/docs/ui/account/hooks.md +9 -2
  110. package/dist/skill/docs/ui/admin/index.md +1 -1
  111. package/package.json +1 -1
  112. package/src/skill/docs/api/actions.md +73 -2
  113. package/src/skill/docs/api/batch-operations.md +2 -0
  114. package/src/skill/docs/api/caching.md +2 -2
  115. package/src/skill/docs/api/crud.md +13 -0
  116. package/src/skill/docs/api/errors.md +111 -10
  117. package/src/skill/docs/api/index.md +24 -0
  118. package/src/skill/docs/api/openapi.md +8 -0
  119. package/src/skill/docs/api/query-params.md +6 -0
  120. package/src/skill/docs/configure/agents.md +73 -1
  121. package/src/skill/docs/configure/auth.md +7 -1
  122. package/src/skill/docs/configure/bindings.md +55 -0
  123. package/src/skill/docs/configure/cloudflare-access.md +191 -0
  124. package/src/skill/docs/configure/domains.md +1 -1
  125. package/src/skill/docs/configure/index.md +4 -2
  126. package/src/skill/docs/configure/providers.md +2 -1
  127. package/src/skill/docs/configure/tenancy.md +3 -0
  128. package/src/skill/docs/configure/tenant-databases.md +2407 -0
  129. package/src/skill/docs/define/access.md +33 -1
  130. package/src/skill/docs/define/actions/defining.md +118 -1
  131. package/src/skill/docs/define/actions/scoped-db.md +32 -8
  132. package/src/skill/docs/define/areas.md +145 -2
  133. package/src/skill/docs/define/diagnostics.md +160 -21
  134. package/src/skill/docs/define/encryption.md +13 -2
  135. package/src/skill/docs/define/fga.md +320 -42
  136. package/src/skill/docs/define/firewall.md +4 -0
  137. package/src/skill/docs/define/index.md +1 -0
  138. package/src/skill/docs/define/read.md +39 -0
  139. package/src/skill/docs/define/relationships.md +30 -12
  140. package/src/skill/docs/define/schema.md +2 -0
  141. package/src/skill/docs/define/scopes.md +393 -9
  142. package/src/skill/docs/define/sealed-protocol.md +67 -12
  143. package/src/skill/docs/define/transitions.md +4 -1
  144. package/src/skill/docs/define/triggers.md +55 -1
  145. package/src/skill/docs/platform/api-contract/index.md +4 -2
  146. package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
  147. package/src/skill/docs/platform/auth/using-auth.md +1 -1
  148. package/src/skill/docs/platform/database/d1.md +112 -3
  149. package/src/skill/docs/platform/database/data-migrations.md +3 -1
  150. package/src/skill/docs/platform/database/neon.md +10 -2
  151. package/src/skill/docs/platform/queues/handlers.md +48 -16
  152. package/src/skill/docs/platform/queues/using-queues.md +16 -0
  153. package/src/skill/docs/platform/realtime/durable-objects.md +285 -17
  154. package/src/skill/docs/platform/realtime/index.md +9 -6
  155. package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
  156. package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
  157. package/src/skill/docs/platform/schedules/index.md +1 -1
  158. package/src/skill/docs/platform/storage/r2.md +10 -1
  159. package/src/skill/docs/platform/storage/using-r2.md +42 -1
  160. package/src/skill/docs/tooling/output.md +9 -2
  161. package/src/skill/docs/ui/account/features/admin.md +5 -3
  162. package/src/skill/docs/ui/account/hooks.md +9 -2
  163. package/src/skill/docs/ui/admin/index.md +1 -1
  164. package/dist/codex/AGENTS.md +0 -290
  165. package/dist/commands/build.test.d.ts.map +0 -1
  166. package/dist/commands/codex.d.ts +0 -16
  167. package/dist/commands/codex.d.ts.map +0 -1
  168. package/dist/commands/codex.js +0 -159
  169. package/dist/commands/codex.js.map +0 -1
  170. package/dist/commands/compile.d.ts +0 -62
  171. package/dist/commands/compile.d.ts.map +0 -1
  172. package/dist/commands/compile.js +0 -830
  173. package/dist/commands/compile.js.map +0 -1
  174. package/dist/commands/compile.test.d.ts.map +0 -1
  175. package/dist/commands/init.d.ts +0 -6
  176. package/dist/commands/init.d.ts.map +0 -1
  177. package/dist/commands/init.js +0 -405
  178. package/dist/commands/init.js.map +0 -1
  179. package/dist/commands/migrate.test.d.ts.map +0 -1
  180. package/dist/commands/migrations.test.d.ts.map +0 -1
  181. package/dist/commands/push.test.d.ts.map +0 -1
  182. package/dist/commands/schema.test.d.ts.map +0 -1
  183. package/dist/docs/content.d.ts +0 -7
  184. package/dist/docs/content.d.ts.map +0 -1
  185. package/dist/docs/content.js +0 -672
  186. package/dist/docs/content.js.map +0 -1
  187. package/dist/docs/index.test.d.ts.map +0 -1
  188. package/dist/lib/action-harvest.test.d.ts.map +0 -1
  189. package/dist/lib/api-client.test.d.ts.map +0 -1
  190. package/dist/lib/artifact-routing.test.d.ts.map +0 -1
  191. package/dist/lib/auth.test.d.ts.map +0 -1
  192. package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
  193. package/dist/lib/compiler-floor.test.d.ts.map +0 -1
  194. package/dist/lib/config-id-splice.test.d.ts.map +0 -1
  195. package/dist/lib/config-sync.test.d.ts.map +0 -1
  196. package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
  197. package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
  198. package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
  199. package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
  200. package/dist/lib/file-loader.test.d.ts.map +0 -1
  201. package/dist/lib/file-writer.test.d.ts.map +0 -1
  202. package/dist/lib/helpers.d.ts +0 -39
  203. package/dist/lib/helpers.d.ts.map +0 -1
  204. package/dist/lib/helpers.js +0 -299
  205. package/dist/lib/helpers.js.map +0 -1
  206. package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
  207. package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
  208. package/dist/lib/migrations/executor.test.d.ts.map +0 -1
  209. package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
  210. package/dist/lib/migrations/lock.test.d.ts.map +0 -1
  211. package/dist/lib/migrations/paths.test.d.ts.map +0 -1
  212. package/dist/lib/migrations/plan.test.d.ts.map +0 -1
  213. package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
  214. package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
  215. package/dist/lib/migrations/staging.test.d.ts.map +0 -1
  216. package/dist/lib/neon-canary.test.d.ts.map +0 -1
  217. package/dist/lib/neon-target.test.d.ts.map +0 -1
  218. package/dist/lib/neon.test.d.ts.map +0 -1
  219. package/dist/lib/prepare-output.test.d.ts.map +0 -1
  220. package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
  221. package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
  222. package/dist/lib/shell.test.d.ts.map +0 -1
  223. package/dist/lib/sweep-stale.d.ts +0 -25
  224. package/dist/lib/sweep-stale.d.ts.map +0 -1
  225. package/dist/lib/sweep-stale.js +0 -179
  226. package/dist/lib/sweep-stale.js.map +0 -1
  227. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  228. package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
@@ -0,0 +1,2407 @@
1
+ # Database per Tenant
2
+
3
+ Set `tenancy.isolation: 'durable-object'` to give every organization its own
4
+ SQLite database. Organization-scoped tables move out of the shared features D1
5
+ into one Durable Object per organization. Each tenant's reads and writes land
6
+ on its own object, not on one central database.
7
+
8
+ ```ts title="quickback/quickback.config.ts"
9
+ import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
10
+
11
+ export default defineConfig({
12
+ name: "events-app",
13
+ template: "hono",
14
+ features: { organizations: true },
15
+ providers: {
16
+ runtime: defineRuntime("cloudflare"),
17
+ database: defineDatabase("cloudflare-d1"),
18
+ auth: defineAuth("better-auth", { plugins: { organization: true } }),
19
+ },
20
+ tenancy: {
21
+ isolation: "durable-object",
22
+ key: "organization",
23
+ jurisdiction: "eu", // optional: pin every tenant object to a jurisdiction
24
+ backup: { bucket: "TENANT_BACKUPS", every: "6h", retainDays: 90 },
25
+ lookups: { inviteCode: { table: "invites", column: "code", hash: true } },
26
+ },
27
+ });
28
+ ```
29
+
30
+ | Option | Default | Effect |
31
+ |---|---|---|
32
+ | `isolation` | `'shared'` | `'shared'`: one features D1 with `organization_id` on every row. `'durable-object'`: one SQLite Durable Object per organization. |
33
+ | `key` | `'organization'` | The tenant key. Only the active organization is supported. |
34
+ | `jurisdiction` | none | `'eu'` or `'fedramp'`. Every tenant object is created in that jurisdiction. Fixed once deployed: changing it fails the build (`TENANCY_JURISDICTION_CHANGED`), because the new value addresses a different, empty namespace. |
35
+ | `backup` | none | Alarm-driven dumps of every tenant object to R2: `bucket` (the tenant Worker's R2 binding, default `TENANT_BACKUPS`), `bucketName` (default `<name>-tenant-backups`), `every` (`30m` / `6h` / `1d`, at least 15 minutes, default `6h`; or `'off'`: no scheduled dumps — point-in-time recovery is the routine backup, and the bucket only serves operator backups, dump restores and moves), `retainDays` (default 30). See [Backups and restore](#backups-and-restore). |
36
+ | `lookups` | none | Platform lookup indexes: `name → { table, column, hash? }` on a tenant table. `hash: true` stores a keyed hash, never the value (credentials). See [Lookup indexes](#lookup-indexes). |
37
+ | `outbox` | `{ receipts: { retainDays: 7, maxRows: 50000 } }` | Delivery receipts: one row per outbox entry the edge delivered or failed, kept `retainDays` and at most `maxRows` per object. `receipts: false` keeps none. See [Outbox delivery](#outbox-delivery). |
38
+ | `allowNamespaceDeletion` | `false` | Permit deleting the tenant class. See [Deleting the namespace](#deleting-the-namespace). |
39
+ | `vars` | none | Non-secret Worker vars tenant code may read as `env.<NAME>`. See [Vars in tenant code](#vars-in-tenant-code). |
40
+ | `operator.http` | unset (every route, with a warning) | `false`: no generated operator routes at all; `{ allow: [...] }`: only the named routes. See [Operator routes](#operator-routes). |
41
+ | `operator.purge` | deprecated — use `operator.http` | `true`, or `false` when your code imports `purgeTenant`: mount the raw `POST /tenants/:id/purge`. Refused beside `operator.http`. |
42
+
43
+ Nothing changes for projects that leave `isolation` unset.
44
+
45
+ ## Two Workers
46
+
47
+ The build emits two Workers from one project.
48
+
49
+ | Worker | Config | Holds |
50
+ |---|---|---|
51
+ | Edge | `wrangler.toml`, `src/index.ts` | Better Auth, routing, the features D1 (platform tables + `tenant_registry`), the CMS and Account SPAs |
52
+ | Tenant | `wrangler.tenant.jsonc`, `src/tenant/index.ts` | `QuickbackTenant`, a SQLite-backed Durable Object running the tenant routes. No Better Auth, no D1, no auth secrets. |
53
+
54
+ Both Workers use the project's `providers.runtime.config.compatibilityDate` (default `2025-01-01`); below `2025-11-17` the tenant Worker also gets the `enable_ctx_exports` flag. Set the newest date your installed wrangler's `workerd` supports.
55
+
56
+ The edge authenticates the request, resolves the tenant (the active
57
+ organization, or a [lookup](#lookup-indexes) for scope tokens), and calls
58
+ `TENANT.getByName(organizationId).handle(request, principal, version)` over
59
+ RPC. The object runs the generated CRUD, batch and action handlers on a
60
+ db built over its own `ctx.storage` (`drizzle-orm/durable-sqlite`). The firewall
61
+ still applies inside the object, and the object refuses a principal for another
62
+ organization (`403 TENANT_MISMATCH`).
63
+
64
+ A tenant table with no routes left (`routes: false` on read, create, update and
65
+ delete) gets no routes module, no mount on either Worker and no OpenAPI path
66
+ items: its paths answer `404` to every caller, signed in or not. Server code
67
+ still reads and writes the table.
68
+
69
+ The tenant Worker declares its class with `exports` (no `[[migrations]]`) and
70
+ carries no binding to itself. The edge binds it with `script_name = "<name>-tenant"`. Deploy the tenant Worker
71
+ first: `npm run deploy` runs `npm run deploy:tenant` before the edge deploy.
72
+ When `providers.runtime.config.accountId` is set, the tenant Worker carries the
73
+ same `account_id` as the edge, so it cannot deploy into a different account.
74
+
75
+ The build refuses to change which tenant Worker a deployed edge binds
76
+ (`TENANCY_TENANT_WORKER_CHANGED`). It reads every `QuickbackTenant` binding in
77
+ the existing `wrangler.toml` (top level and `[env.*]`, in any key order or
78
+ quoting) and compares it with the new config. If a binding cannot be read —
79
+ an inline table, a binding without `script_name`, an edge table with no
80
+ `name`, or a table declared twice — the build fails with
81
+ `TENANCY_TENANT_WORKER_UNKNOWN` instead of skipping the check. Two cases are refused:
82
+
83
+ - a deployed edge script would bind a different tenant script;
84
+ - a tenant script bound today is no longer bound by any target. This covers
85
+ renaming a target's edge and tenant Worker together, and dropping a target.
86
+
87
+ A different tenant script name addresses a new, empty namespace, so every
88
+ tenant would look wiped. To move on purpose, migrate the tenants first, then
89
+ remove the old `TENANT` binding from `wrangler.toml` and rebuild. A build
90
+ without `wrangler.toml` cannot run this check, and warns.
91
+
92
+ ### Named environments
93
+
94
+ With [named environments](/platform/database/d1#named-cloudflare-deployment-environments), every
95
+ target deploys its own pair: its edge Worker (`environments.<key>.name`) and
96
+ its own tenant Worker (`environments.<key>.tenantWorker.name`). The tenant
97
+ Worker's script name owns the `QuickbackTenant` namespace, which holds every
98
+ organization's database. Like `name`, it is required on every target and never
99
+ derived.
100
+
101
+ ```ts
102
+ environments: {
103
+ dev: {
104
+ name: 'events-app-dev',
105
+ tenantWorker: { name: 'events-app-tenant-dev', backupBucketName: 'events-app-tenant-backups-dev' },
106
+ /* worker, bindings, domains … */
107
+ },
108
+ production: {
109
+ name: 'events-app',
110
+ tenantWorker: { name: 'events-app-tenant', backupBucketName: 'events-app-tenant-backups' },
111
+ /* … */
112
+ },
113
+ }
114
+ ```
115
+
116
+ All targets run the same bundle. The build emits:
117
+
118
+ - **`wrangler.toml`**: one `[[env.<key>.durable_objects.bindings]]` per
119
+ target, with `script_name` set to that target's tenant Worker. Durable Object
120
+ bindings do not inherit, and the top level emits no tenant binding, so no
121
+ target can reach another target's tenant databases.
122
+ - **`wrangler.tenant.jsonc`**: no top-level `main` or `exports`, so a bare
123
+ `wrangler deploy -c wrangler.tenant.jsonc` fails with *Missing entry-point*.
124
+ The top-level `name` is an inert placeholder, `<name>-tenant-unselected`.
125
+ A positional entry (`wrangler deploy -c wrangler.tenant.jsonc
126
+ src/tenant/index.ts`) deploys an unbound Worker under that name. Without the
127
+ placeholder, Wrangler would take the `package.json` name (the production
128
+ edge) and deploy tenant code over it. No target may use the placeholder. One `env.<key>` block per
129
+ target carries `main`, `exports`, that target's `account_id` (its `accountId`, or
130
+ `providers.runtime.config.accountId`), its `TENANT_BACKUPS` bucket
131
+ (`backupBucketName`), and the rate-limit namespaces from its own edge stanza.
132
+ - **`package.json`**: `deploy:<key>:tenant`. Each `deploy:<key>` runs it
133
+ before the edge deploy. `dev:tenant` runs the `dev` target. There is no bare
134
+ `deploy:tenant`.
135
+
136
+ The tenant registry, lookups and outbox live in each target's own features D1
137
+ (`worker.bindings.d1.features`). Jobs ride each target's own queues
138
+ (`worker.bindings.queues`).
139
+
140
+ The build refuses:
141
+
142
+ - a target without `tenantWorker.name`;
143
+ - two targets with the same tenant Worker;
144
+ - a backup bucket that is another target's bucket, or one of the same target's
145
+ `worker.bindings.r2Buckets` (the same per-target R2 uniqueness rule as every
146
+ other bucket);
147
+ - a tenant Worker named like an edge or files Worker, or like the top-level
148
+ project `name`;
149
+ - `backupBucketName` missing while `tenancy.backup` is set, or set while it
150
+ is not.
151
+
152
+ Only the target that deploys as the project `name` may reuse the single-target
153
+ `<name>-tenant` script and `<name>-tenant-backups` bucket. Set them on that
154
+ target when you adopt environments in a deployed project, so it keeps its
155
+ tenant databases. The continuity check above refuses any other name for it.
156
+ A `tenantWorker` is also refused when `tenancy.isolation` is not
157
+ `'durable-object'`.
158
+
159
+ The sharing refusals apply even when two targets deploy into different
160
+ Cloudflare accounts (`accountId`), where the same names would not collide.
161
+ This is deliberately conservative. Per-client accounts (one target per client)
162
+ may relax it later.
163
+
164
+ The edge↔tenant contract is versioned (`TENANT_RPC_VERSION` in
165
+ `src/tenant/contract.ts`, the same constant in both Workers). A tenant Worker
166
+ answers versions from `TENANT_RPC_MIN_VERSION` up to its own and returns
167
+ `503 TENANT_RPC_VERSION_MISMATCH` otherwise. The current protocol is version 13
168
+ (version 3 put dump restore under the shared restore fence and added the
169
+ authorization epoch; version 4 adds tenant commands and epoch-carrying restore
170
+ permits; version 5 adds `callJob()` for [result jobs](#result-jobs); version 6
171
+ adds `queue` outbox entries for [platform queues](#platform-queues); version 7
172
+ the bounded backup read; version 8 the `callJob` epoch fence; version 9 the
173
+ backup-fenced purge; version 10 room commit permits; version 11
174
+ [leased outbox delivery](#outbox-delivery); version 12 `revoke` outbox entries
175
+ for [scope revocation](#scope-revocation); version 13 `armSchedules()` for
176
+ [tenant schedules](#tenant-schedules)). An edge below version 11 gets no
177
+ inline claims and keeps using `takeOutbox` / `ackOutbox`. An edge below
178
+ version 12 is never handed a `revoke` entry, by a claim or by `takeOutbox`:
179
+ those entries wait for the new edge, so no revocation is settled unapplied. It still
180
+ accepts version-2 to version-5 edges: no method those edges
181
+ call changed meaning, so deploying the tenant Worker first opens no 503 window.
182
+ An edge older than version 6 is handed no outbox entries from the first
183
+ `queue` entry on, so it never acknowledges a message it would not send; those
184
+ entries wait, in order, for the new edge,
185
+ and a version-2 edge's dump restore fails closed until the edge is deployed.
186
+ A percentage (gradual) deploy of the tenant Worker is safe from version 3
187
+ to 4. While it runs, some tenant objects and their control objects use the old
188
+ code and some the new, and both directions work. A control object answers an
189
+ older holder's permit request with the plain token string that holder expects,
190
+ and the holder releases it as before. A version-4 holder whose control object
191
+ still runs version 3 gets a version-mismatch refusal before anything is
192
+ written, then retries at `TENANT_RPC_MIN_VERSION` with the old protocol. Its
193
+ permit then carries no authorization epoch, so `command()` answers
194
+ `unavailable` / `TENANT_RPC_VERSION_MISMATCH` until that control object is
195
+ upgraded. `handle()`, jobs and alarms keep serving, and the restore fence is
196
+ the same permit table either way. `command()` itself accepts only version 4
197
+ (`TENANT_PERMIT_VERSION`). Upgrading from version 1 requires both Workers to
198
+ be deployed. Old edge
199
+ calls fail closed while the tenant Worker is upgraded first.
200
+
201
+ ### Tenant commands
202
+
203
+ Besides `handle()`, the object has one more entry point for trusted edge code:
204
+ `command(version, request)`. It runs a **compiler-owned** program inside the
205
+ object. Callers pick a command by name and pass its fields. They never send
206
+ SQL, callbacks, method names or credentials, and app code cannot add commands.
207
+ Every name is reserved under `qb.*`.
208
+
209
+ ```ts
210
+ import { tenantCommand } from './lib/tenants';
211
+
212
+ const res = await tenantCommand(env, organizationId, { name: 'qb.epoch' });
213
+ if (res.status === 'ok') res.reply.authEpoch; // { tenantId, authEpoch, lifecycle: { state, schemaVersion } }
214
+ ```
215
+
216
+ | Command | Mode | Reply |
217
+ |---|---|---|
218
+ | `qb.epoch` | read | `{ tenantId, authEpoch, lifecycle: { state: 'active', schemaVersion } }`: the [authorization epoch](#authorization-epoch) |
219
+ | `qb.admitScope` | read | Registered only when a scope kind is [tenant-backed](#tenant-admission-qbadmitscope). `{ kind, instanceId, tenantId, authEpoch, roles, subjectId, provingTable, subKeys }`, or `denied` with `SCOPE_EPOCH`, `SCOPE_NOT_FOUND`, `SCOPE_NO_ROLE`, `SCOPE_WRONG_SUBJECT` or `SCOPE_AMBIGUOUS` |
220
+ | `qb.scopeGrantRead` | read | Registered only when a tenant-backed kind declares [`oauth.serverGrant`](#server-issued-grants). `{ kind, instanceId, subjectId, tenantId, authEpoch, linkedUserId, roles, subject, instance }` (identity and instance projections as JSON), or `denied` with `SCOPE_NOT_FOUND` or `SCOPE_GRANT_SUBJECT_DENIED` |
221
+ | `qb.scopeGrantLink` | write | Same registration. `{ kind, instanceId, subjectId, tenantId, authEpoch, outcome: 'linked' \| 'unchanged' }`, or `denied` with `SCOPE_EPOCH`, `SCOPE_NOT_FOUND`, `SCOPE_GRANT_SUBJECT_DENIED` or `SCOPE_GRANT_LINK_CONFLICT` |
222
+ | `qb.roomAccess` | read | Registered only when a resource-backed realtime room is on a tenant table ([Tenant rooms](/platform/realtime/durable-objects#tenant-rooms)). `{ room }` when the room's row passes the table firewall for a member of this organization, else `denied` with `ROOM_ACCESS_DENIED` |
223
+
224
+ `tenantCommand` first reads the organization's `tenant_registry` row, and wakes
225
+ the object only when the registry vouches for it:
226
+
227
+ | Registry row | Result |
228
+ |---|---|
229
+ | None: the platform has never served the tenant, or its first report is still in flight | `unavailable` / `TENANT_NOT_PROVISIONED` (retryable). The object is not woken, so no empty tenant database is created. |
230
+ | `purged` | `unavailable` / `TENANT_PURGED`, without waking the object |
231
+ | Written under another `tenancy.jurisdiction` | `unavailable` / `TENANT_JURISDICTION_MISMATCH` |
232
+ | Registry read fails | `unavailable` / `TENANT_UNAVAILABLE` |
233
+ | Any other state | The object decides (archived, migration and restore are checked there) |
234
+
235
+ A tenant gets its row when it first serves a request or a job, or when an
236
+ operator provisions it (`POST /tenants/:id/provision`, `provisionTenantTarget`
237
+ in `src/lib/tenants.ts`: verified against Better Auth's organization table
238
+ first). Until one of those, a new organization's commands answer
239
+ `TENANT_NOT_PROVISIONED`. `denied` is kept for definitive refusals made by a command.
240
+ Pass only a server-verified organization id, never one taken from the request.
241
+ The HTTP forwarder (`tenantForward`) does not read the registry: it routes the
242
+ authenticated principal's organization, so it adds no D1 read per request.
243
+
244
+ The object then checks each request in this order:
245
+
246
+ 1. The RPC version. `command()` accepts only version 4 or later
247
+ (`TENANT_PERMIT_VERSION`). Then `TENANT_COMMAND_FINGERPRINT`, a hash of the
248
+ command registry that both Workers carry in `src/tenant/contract.ts`. It is
249
+ checked before the name, so a split deploy reports itself as one. Then the
250
+ command name and the exact request shape: unknown fields are refused, and
251
+ string fields are capped at 512 characters. Then the target: the request's
252
+ `tenantId` must be this object's name. Partition objects and control objects
253
+ serve no commands. Each failure throws (`TENANT_RPC_VERSION_MISMATCH`,
254
+ `TENANT_COMMAND_FINGERPRINT_MISMATCH`, `TENANT_COMMAND_INVALID`) before the
255
+ command reads any tenant data. As with every RPC, waking the object still
256
+ runs its own [migrate on wake](#migrations) first.
257
+ 2. The [restore permit](#restore-quarantine). The permit also carries the
258
+ authorization epoch, and no restore can begin while it is held. A pending
259
+ restore answers `unavailable` / `TENANT_RESTORE_PENDING`.
260
+ 3. Archived, purged and unmigrated objects answer `unavailable`
261
+ (`TENANT_ARCHIVED`, `TENANT_PURGED`, `TENANT_MIGRATION_FAILED`).
262
+ 4. The body runs in one `ctx.storage.transactionSync`, with no `await`. A write
263
+ command marks the object dirty inside that transaction, so the next backup
264
+ includes it, and the backup is scheduled after the transaction commits.
265
+
266
+ `tenantCommand(env, tenantId, request)` returns
267
+ `{ status: 'ok', reply } | { status: 'denied', code } | { status: 'unavailable', code }`.
268
+ It checks the reply against the command's schema; a reply of the wrong shape
269
+ becomes `unavailable` / `TENANT_COMMAND_REPLY_INVALID`. Read commands are
270
+ retried once after an object reset or a retryable RPC error. Write commands are
271
+ sent once, and overloaded objects are never retried. Failures carry codes only:
272
+ `TENANT_UNAVAILABLE`, `TENANT_OVERLOADED`, `TENANT_DEPTH_EXCEEDED`,
273
+ `TENANT_RESTORE_PENDING`, the registry codes above, or one of the refusal codes above. A version or
274
+ fingerprint mismatch is `unavailable`, not `denied`: it is deploy skew, not a
275
+ policy decision. For a write command, `unavailable` means the outcome is
276
+ unknown: the write may have committed before the failure. Logs record the
277
+ command name and code, never the request or the error text. A malformed (or
278
+ `null`) request, an unknown command, or an organization id that is reserved, contains
279
+ `:` or is longer than 512 characters throws.
280
+
281
+ Commands do not carry the wake report or the outbox signal that `handle()`
282
+ responses do. A command write that queues outbox entries (lookup, audit,
283
+ realtime, jobs) is applied on the object's next drain: the next proxied request
284
+ that reports a non-empty outbox, the object's next alarm (which asks the edge to
285
+ drain it), `syncTenants(env)`, or `drainTenantOutbox`.
286
+
287
+ ## Placement
288
+
289
+ The firewall decides where each table lives. A table with an organization arm
290
+ **anywhere** in its firewall is a **tenant** table: at the top level
291
+ (`q.scope("organization")`), inside `all:`, inside `any:`, or `optional`. So
292
+ "org staff OR the attendee of one event" is a tenant table too. An `exception`
293
+ firewall never is. Every other table is a **platform** table, served by the
294
+ edge from the features D1. Every compile prints the resolved table:
295
+
296
+ ```text
297
+ [quickback] tenancy: durable-object — table placement
298
+ table placement why
299
+ attendees tenant organization arm (any:)
300
+ notes platform no organization firewall
301
+ projects tenant organization firewall
302
+ tasks tenant organization firewall
303
+ ```
304
+
305
+ ### Tenant ownership
306
+
307
+ Inside the object, a tenant table's effective firewall is the authored one
308
+ behind a **tenant pin**:
309
+
310
+ ```text
311
+ organizationId = ctx.tenantId AND (<the firewall you wrote>)
312
+ ```
313
+
314
+ `ctx.tenantId` is the organization the object serves. The object sets it from
315
+ its own name on every request and job, overwriting whatever the caller sent;
316
+ the edge strips it before forwarding. Three things follow:
317
+
318
+ - **Reads.** Every read is pinned to the object's organization, including
319
+ `skipTenantScopes` relationship probes and the sysadmin escape. A row
320
+ naming another organization — a bad copy or restore — is invisible to
321
+ everyone.
322
+ - **Writes.** Every insert stamps `organizationId` from `ctx.tenantId`: CRUD
323
+ create, changesets, upserts, batch and the action `db`. An attendee with no
324
+ active organization creates rows in the right tenant.
325
+ - **Who sees what is still the authored firewall.** `any: [{ field:
326
+ 'organizationId', equals: 'ctx.activeOrgId' }, { field: 'eventId', equals:
327
+ 'ctx.scope.event' }]` lowers to *tenant AND (org member OR attendee of this
328
+ event)*. The org arm means org membership. A relationship or scope caller
329
+ never gets `ctx.activeOrgId` from its relationship row, so it reads its own
330
+ event's rows, never the organization's. An org-only table is for members
331
+ only: a non-member's list or create gets `403 ORG_REQUIRED`, and a read by
332
+ id finds nothing. The pin itself never satisfies that check — creates on a
333
+ members-only table still need the caller's own `ctx.activeOrgId`, while an
334
+ org-OR-scope table's creates are bounded by the
335
+ [firewall-on-write check](/define/firewall#firewall-on-write).
336
+
337
+ `ctx.tenantId` is compiler-owned: the build adds the pin for you, and a
338
+ firewall that names `ctx.tenantId` itself is a compile error, in either
339
+ isolation mode.
340
+
341
+ A tenant object holds one organization, pinned through one column. A firewall
342
+ whose org arms bind two different organization columns (a buyer and a seller
343
+ org on one row) fails with `TENANCY_ORG_COLUMNS`. An `any: [org, owner]` table
344
+ that moves into tenant objects prints a warning: each request reaches one
345
+ object, so an owner without an active organization no longer reaches their
346
+ rows across organizations.
347
+
348
+ The pin does not change the edge↔tenant contract, so `TENANT_RPC_VERSION`
349
+ stays the same. The pin is compiled into the tenant Worker's own code, the
350
+ tenant object sets `ctx.tenantId` itself, and the edge strips any forwarded
351
+ value. A mixed rollout is therefore safe in both directions: an older edge
352
+ cannot supply a tenant, and an older tenant Worker never reads one.
353
+
354
+ ### Placement changes on deployed tables
355
+
356
+ Once a project runs with `isolation: 'durable-object'`, its features D1 holds
357
+ only platform tables. So a table that is in the deployed features D1 (the
358
+ `quickback/drizzle/features` snapshot) and that the firewall places in tenant
359
+ objects is moving — a shared project switching to `'durable-object'`, or an
360
+ `any:` / optional organization arm that the old rule placed on the platform.
361
+ Without a declared placement it fails the build with
362
+ `TENANCY_PLACEMENT_MOVED`: deploying would leave
363
+ its rows in D1 while each tenant object serves an empty table. Declare
364
+ `placement: 'tenant'` once its rows are copied into each organization's object,
365
+ or `placement: { platform: true, crossTenant: true }` to keep it where it is.
366
+
367
+ `quickback build` sends the deployed table list as
368
+ `migration.priorState.existingFeaturesTables` (an older CLI does not). A build
369
+ with no deployed-schema facts at all — no `existingFeaturesTables` and no
370
+ features history, or a latest snapshot that does not parse — cannot tell, so every table whose placement derives
371
+ `tenant` only from an `any:` / optional organization arm fails with
372
+ `TENANCY_PLACEMENT_UNCONFIRMED` until it declares its placement (or the build
373
+ runs with a current CLI). A project with no migration history at all is
374
+ greenfield: the CLI sends an empty list, and a raw-files validate compile
375
+ treats missing history the same way.
376
+
377
+ Override it per table with `placement`. An organization-scoped table kept on
378
+ the platform must say so, because every tenant's rows then share one database:
379
+
380
+ {/* doc-compile: skip — fragment of a feature() resource config */}
381
+ ```ts
382
+ placement: { platform: true, crossTenant: true },
383
+ ```
384
+
385
+ All features sharing a partition kind must use the same key column.
386
+ All tables in one feature share a placement, because they share one schema
387
+ file and one route file. To shard a high-volume feature further, see
388
+ [Partitions](#partitions).
389
+
390
+ Every compile warns when a tenant table's `organizationId` or a foreign-key
391
+ column has no index: each request filters, and each FK check reads, on it.
392
+
393
+ ### Admission tables stay on the platform
394
+
395
+ Only a [tenant-backed scope kind](#tenant-backed-scope-kinds), its
396
+ [tenant namespaces](#tenant-namespaces) and its tickets admit inside tenant
397
+ objects. Every other admission and request-time authorization path runs on the
398
+ edge Worker and reads its tables from the platform D1. If a tenant object held
399
+ one of those tables, the D1 copy would be missing. Or, during a migration, it
400
+ would be a stale copy whose rows keep admitting subjects the tenant has
401
+ already revoked. So the build fails with `TENANCY_ADMISSION_DEPENDENCY` when
402
+ any of them reads a tenant or partition table. A scope kind that reads a
403
+ tenant table but can't be tenant-backed fails with the planner's own codes
404
+ instead (see [Which kinds can be tenant-backed](#which-kinds-can-be-tenant-backed)),
405
+ and a namespace with `TENANCY_NAMESPACE_*`:
406
+
407
+ | Surface | Tables checked | Paths named in the error |
408
+ |---|---|---|
409
+ | `authz.scopes.<kind>` | each role's relationship tables (`from` and any `hops`), each role's `self.table`, and the instance table | `POST /scope/v1/enter` (when a role is `subject: 'user' \| 'both'`), `ctx.mintScope` (when a role is `'supplied' \| 'both'`), instance-bound OAuth (authorize, code exchange, refresh, `issueScopeGrant`, bound namespace and ws-ticket checks), the `ctx.self` recheck on every action route, and the scope refresh / `mintScope` of each namespace using the kind's relationships |
410
+ | `authz.namespaces.<name>` | relationship lanes' tables and the `loads` table | namespace gate and hydration |
411
+ | `realtime.wsTicket` | `scopeTable`, the tables behind `role` / `access.authzRole`, and the `namespace` lanes | ws-ticket mint |
412
+ | A platform feature | every relationship its CRUD, read, view, masking and action `access`, and its `firewall` arms, resolve: `authz.roles` relationship roles, `authz.rules`, `authz.permissions` (including `arrows` `from` / `to`) and direct `via` arms, with `hops` and `loads` | request-time authorization |
413
+ | A platform action with `anchor` | the relationship's tables and its `reach` tables | anchored transaction |
414
+ | A platform action's `refs` and `operator` | each ref's `table`, each `ownedVia.junction`, and `operator.target.table` | loaded and firewalled before `execute` |
415
+ | A platform table's derived JSON keys | each `derivedFrom.table` | CRUD reads and action `requires:` |
416
+ | A live view (`defineView`) | `root` and every project-table `include` | the view materializer (`GET /views/...`, ws-ticket view lane) |
417
+
418
+ The error names the surface, the paths that depend on it, and each tenant
419
+ table with its placement. A scope kind whose instance table is ambiguous also
420
+ fails: set `authz.scopes.<kind>.instance`. A kind with no resolvable instance
421
+ table loads no instance, so only its relationship tables are checked, unless
422
+ the kind is also a `tenancy.lookups` key. Then its tokens are routed by an
423
+ instance id that no table binds to a tenant, so the build fails until you set
424
+ `instance`.
425
+
426
+ The table above is what the compiler names in friendly messages. Three more
427
+ checks stand behind it:
428
+
429
+ - **Platform action source.** A platform action or feature `lib/` file that
430
+ names a tenant table fails the build. So does a schedule
431
+ (`services/schedules`), a queue handler that is not a tenant job, and any
432
+ `quickback/lib` helper, auth hook (`quickback/hooks`), middleware
433
+ (`quickback/middlewares`) or Better Auth plugin (`quickback/plugins`) the
434
+ edge Worker loads (scanned per module). That covers its export name as an identifier, its SQL name as a
435
+ string (an inline `sqliteTable("projects", …)`), and `FROM` / `JOIN` /
436
+ `INTO` / `UPDATE` / `TABLE <name>` in any string or template (in actions,
437
+ only with `allowRawSql`). The scan is conservative: a local variable that
438
+ only shares a tenant table's name is refused too, so rename it. Instead of a
439
+ cron sweep, declare a [tenant schedule](#tenant-schedules) (each object runs
440
+ its own work on its own alarm) or have the edge arm a tenant job
441
+ (`scheduleTenantJob`); to read a tenant's data from the edge, call a
442
+ [result job](#result-jobs).
443
+ - **The emitted edge bundle.** After all files are generated, the compiler
444
+ walks the edge Worker's runtime imports from `src/index.ts`. It follows
445
+ relative imports, `tsconfig.json` `paths` aliases such as `~/`,
446
+ `export … from`, and literal `import()` / `require()`. Type-only imports are
447
+ skipped. The build fails if an edge module imports a tenant feature's module
448
+ (its schema, table, resource or routes), or calls `import()` / `require()`
449
+ with a computed path the walk can't follow.
450
+ - **At runtime.** `src/lib/firewall-registry.ts` is the one edge module allowed
451
+ to import tenant modules. It maps every table to its firewall for the scoped
452
+ `db`. Only its tenant imports are exempt; its other imports are still walked.
453
+ Its tenant entries throw `TENANT_TABLE_ON_EDGE` outside the tenant Worker, so
454
+ an edge query that slips past the compile-time checks fails instead of
455
+ reading D1. A raw SQL string that never goes through the scoped `db` is caught
456
+ only by the compile-time scan.
457
+
458
+ To fix it, keep those tables on the platform. An organization-scoped one needs
459
+ `placement: { platform: true, crossTenant: true }`. A platform table can't
460
+ hold a foreign key into a tenant table (`TENANCY_FK_PLATFORM_TO_TENANT`), so
461
+ move the tables it references with it, or drop the reference. Or remove the
462
+ dependency.
463
+
464
+ ### Tenant-backed scope kinds
465
+
466
+ An instance-bound OAuth kind (`authz.scopes.<kind>.oauth`) whose whole
467
+ admission program reads one organization object is **tenant-backed**: its
468
+ admission, its namespaces and its tickets run in that object, and its tables
469
+ never exist in the platform D1. Every compile decides this from the
470
+ requirements in [Which kinds can be tenant-backed](#which-kinds-can-be-tenant-backed);
471
+ there is no switch. A tenant-backed kind gets this identity contract:
472
+
473
+ - **Pinned grant references.** An instance-bound OAuth grant stores
474
+ `qb2:<kind>:<tenantId>:<instanceId>:<mode>:<epoch>[:<ceiling>]` instead of
475
+ `<kind>:<id>`. `mode` is `discover` (the authorize flow: any of the kind's
476
+ roles) or `exact` (`issueScopeGrant`: only the URI-encoded `{ roles,
477
+ subjectId, provingTable }` ceiling). A reference parses only in its one
478
+ canonical spelling. An exact reference without `provingTable` fails
479
+ refresh with `invalid_grant` (reauthorize); the table is never guessed. An older unpinned grant for the kind fails refresh with
480
+ `invalid_grant`, so the user reauthorizes. The compiler never guesses a
481
+ tenant for it.
482
+ - **Where the tenant comes from.** At authorize it comes from the kind's
483
+ [lookup](#lookup-indexes) (`tenancy.lookups.<kind>`), never from the caller's
484
+ active organization or the request. If the lookup matches several
485
+ organizations, the request fails with `invalid_request`. If it has no row
486
+ yet, the request fails with `temporarily_unavailable` (retry).
487
+ `issueScopeGrant` also accepts a `tenantHint`, the organization that trusted
488
+ server code read from the credential row. The hint is used only while the
489
+ lookup has no row. A lookup that disagrees with it refuses. Once issued, a
490
+ grant always routes to its pinned tenant, even if the lookup changes later.
491
+ - **Authorization epoch.** The grant pins the tenant's
492
+ [authorization epoch](#authorization-epoch), read with the `qb.epoch`
493
+ [tenant command](#tenant-commands). Every code exchange and refresh compares
494
+ it with the current epoch. After a restore they differ, and the grant fails
495
+ with `invalid_grant`, so the user signs in again.
496
+ - **v2 claims.** The `qb_scope` claim gains `v: 2`, `tenantId` and `epoch`
497
+ (and `provingTable` from admission). The bound lane refuses a token for a
498
+ tenant-backed kind without them (`401`). `ctx.oauth.boundTo` becomes
499
+ `{ kind, id, tenantId, epoch }`, and the edge routes the request to
500
+ `boundTo.tenantId`. It never uses a lookup or `activeOrgId` for that token.
501
+ - **Revocation.** For a tenant-backed kind, `revokeScopeGrant` requires the
502
+ `tenantId` the grant pins. It deletes the user's pinned grants for that
503
+ instance in both modes, at every epoch and under any tenant. Instance ids are
504
+ collision-resistant, so this also catches a grant pinned through a wrong
505
+ hint. User-wide revocation (ban, sign-out everywhere) deletes the kind's
506
+ pinned and unpinned grants.
507
+ - **Kind names.** `qb2` is reserved as a scope kind name in every project. A
508
+ tenant-backed kind's name must be an identifier, because it is a segment of
509
+ its grant references.
510
+ - **Realtime.** Rooms on tenant tables become `t1:<tenant>:<key>`, and the
511
+ kind's identity tags become
512
+ `t1:<tenant>:scope:<kind>:<provingTable>:<subjectId>`. See
513
+ [Durable Objects → Tenant rooms](/platform/realtime/durable-objects#tenant-rooms).
514
+ - **Id contract.** The kind's instance table and each role's proving table
515
+ need server-generated, collision-resistant ids across every tenant object.
516
+ The build fails with `TENANCY_ADMISSION_ID_STRATEGY` when the table has
517
+ `generateId: false | 'short' | 'serial'`, `allowClientIds: true`, or a
518
+ numeric primary key.
519
+
520
+ #### Which kinds can be tenant-backed
521
+
522
+ The compiler plans each scope kind's admission program: the instance read plus
523
+ one probe per user-provable role, in the kind's declared
524
+ [precedence](/define/scopes#subject-precedence). An OAuth kind can run that
525
+ program, and every other path it has, inside its tenant object only when all
526
+ of these hold. The first five are permanent: those paths never run in a tenant
527
+ object. A kind reading a tenant table that misses any of them fails the build
528
+ with each missing requirement under its own code:
529
+
530
+ | Code | Requirement |
531
+ |---|---|
532
+ | `TENANCY_LEGACY_SCOPE_ENTER` | The kind declares `oauth`. `POST /scope/v1/enter` runs on the edge against D1 and pins no tenant, so a kind admitted only through it can't read tenant tables. |
533
+ | `TENANCY_LEGACY_SCOPE_MINT` | Every role is `subject: 'user'`. A `'supplied'` / `'both'` role can be minted by `ctx.mintScope` on the edge, with no tenant. |
534
+ | `TENANCY_ADMISSION_SELF` | No role declares `self: { table }`. The `ctx.self` recheck runs on every edge action route. |
535
+ | `TENANCY_ADMISSION_HOPS` | No role proves through a relationship with `hops`. Tenant admission proves the relationship's own table. |
536
+ | `TENANCY_NAMESPACE_MINT` | No namespace on the kind's `:param` declares `mintScope` or `acceptScope`. A legacy scope token carries no tenant. |
537
+ | `TENANCY_ADMISSION_MIXED_PLACEMENT` | Every table the kind reads (instance, relationship tables and `hops`, `self.table`) lives in the tenant object. None on the platform. |
538
+ | `TENANCY_ADMISSION_PARTITIONED` | None of them lives in a [partition](#partitions). |
539
+ | `TENANCY_ADMISSION_UNRESOLVED_INSTANCE` | The instance table resolves to exactly one table. Set `authz.scopes.<kind>.instance`. |
540
+ | `TENANCY_ADMISSION_TENANT_COLUMN` | The instance table and every proving table have an organization column. |
541
+ | `TENANCY_ADMISSION_LOOKUP` | `tenancy.lookups.<kind>` indexes the instance table's primary key: `{ table: '<instance>', column: '<pk>' }`. |
542
+ | `TENANCY_ADMISSION_SQL_HELPER` | No role proves through a SQL helper (Postgres). |
543
+
544
+ Every error lists all the violations at once. A kind that meets them all is
545
+ tenant-backed in every compile.
546
+
547
+ #### Tenant admission (`qb.admitScope`)
548
+
549
+ For a tenant-backed kind, the edge never reads the kind's tables. Every
550
+ admission (authorize, code exchange, refresh, `issueScopeGrant`, the bound
551
+ ws-ticket mint) goes through the generated dispatcher `src/lib/scope-admission.ts`.
552
+ Platform kinds keep their D1 evaluator there. A tenant-backed kind sends one
553
+ `qb.admitScope` [command](#tenant-commands) to the pinned tenant. The object
554
+ runs `admitLocal` (`src/tenant/scope-admission.ts`) in one synchronous SQLite
555
+ read, under the restore permit:
556
+
557
+ 1. The request's epoch must equal the permit's epoch (`SCOPE_EPOCH`).
558
+ 2. The instance row, read through its own firewall with tenant scopes stripped
559
+ (soft deletes still apply), must exist once and belong to this tenant
560
+ (`SCOPE_NOT_FOUND`).
561
+ 3. Each user-provable role is probed in precedence order, with the same
562
+ predicates the D1 evaluator uses. An exact ceiling probes only its own roles
563
+ on its own proving table, with `id = subjectId`. A row whose organization is
564
+ not the tenant never matches, even if it was copied in.
565
+ 4. The first role with any match chooses the subject `(provingTable, id)`. Two
566
+ rows on that role deny the admission (`SCOPE_AMBIGUOUS`). Every later role
567
+ probes only the chosen row, so a later role's duplicate rows never deny. The
568
+ reply carries only that subject's roles and sub-keys, plus `provingTable`.
569
+ It never unions roles across subjects.
570
+
571
+ The edge checks every reply field against the request: kind, instance,
572
+ tenant, epoch, known roles on one proving table, the ceiling's subject, roles
573
+ and table, and declared sub-keys only. A reply that disagrees is treated as
574
+ `unavailable`, never as an admission. Errors map like this:
575
+
576
+ | Outcome | At authorize | At code exchange / refresh | ws-ticket (bound or session) |
577
+ |---|---|---|---|
578
+ | denied | `access_denied` | `invalid_grant` | `403` |
579
+ | unavailable (archived, purged, restoring, migrating, unreachable) | `temporarily_unavailable` (503) | `temporarily_unavailable` (503) | `503 TENANT_ADMISSION_UNAVAILABLE` |
580
+
581
+ The admission policy (kinds, precedence, predicates, sub-keys) is part of the
582
+ command fingerprint, so two Workers built from different policies refuse each
583
+ other. Adding `qb.admitScope` does not change the RPC version: the fingerprint
584
+ covers the whole command registry. So while the two Workers deploy, an edge
585
+ on the previous build gets `unavailable` (`TENANT_COMMAND_FINGERPRINT_MISMATCH`)
586
+ from every command, `qb.epoch` included, until it is deployed too. Bound
587
+ tokens of tenant-backed kinds answer `temporarily_unavailable` in that window.
588
+ Nothing is admitted from a mismatched registry. The tenant bundle imports no Better Auth, no `drizzle-orm/d1` and no
589
+ `scope-oauth`. The legacy `POST /scope/v1/enter` never serves a tenant-backed
590
+ kind; when no other kind remains, the route isn't emitted at all. None of
591
+ these paths reads the platform D1.
592
+
593
+ #### Server-issued grants
594
+
595
+ A tenant-backed kind that declares
596
+ [`oauth.serverGrant`](/define/scopes#server-issued-grants-issuescopegrant)
597
+ gets two more commands. They are reached only through the generated
598
+ `readScopeGrantSubject` and `linkScopeGrantSubject` (in `src/lib/scope-oauth.ts`),
599
+ which the edge action calls with the subject its own credential row names;
600
+ no edge code reads or writes the guest table itself.
601
+
602
+ - **`qb.scopeGrantRead`** selects the instance row and the subject row inside
603
+ one synchronous transaction: object tenant = instance tenant column =
604
+ subject tenant column, subject resource column = the instance id, neither
605
+ row soft-deleted, the subject admittable (the OR of the ceiling roles'
606
+ `where`). It writes nothing.
607
+ - **`qb.scopeGrantLink`** re-runs those checks, returns `unchanged` when the
608
+ subject is already linked to the user, and otherwise runs one conditional
609
+ `UPDATE … SET <user column> = :userId WHERE <all of the above> AND
610
+ (<user column> IS NULL OR <user column> = :replaces) RETURNING id`. Anything
611
+ but exactly one row is `SCOPE_GRANT_LINK_CONFLICT` (still live, linked to
612
+ someone else) or `SCOPE_GRANT_SUBJECT_DENIED`, with nothing written. On a
613
+ link it puts the audit row (`event_kind: 'scope_grant_link'`, a
614
+ `credential-mediated` actor envelope) in the object's outbox in the same
615
+ transaction; the edge drains it to `audit_events`. The request's epoch must
616
+ equal the permit's: a restore between the read and the link denies.
617
+
618
+ Routing follows the kind's lookup; the action's `tenantHint` (the
619
+ organization on its credential row) is used only while the lookup has no
620
+ row, and the object's own equality checks make a wrong hint admit nobody.
621
+ While the object is held, archived, restoring, moving or migrating, both
622
+ commands answer `unavailable`, so the action answers `503` and its credential
623
+ is untouched: nothing spends it before the action's own consume, after
624
+ `issueScopeGrant`. Like `qb.admitScope`, adding these commands does not
625
+ change the RPC version: the command fingerprint covers them (and the
626
+ server-grant program), so a split deploy refuses before any write.
627
+
628
+ #### Tenant namespaces
629
+
630
+ A namespace (`authz.namespaces.<name>`) whose relationship lanes, `loads`
631
+ tables and claimed routes all live in the organization object runs in the
632
+ tenant Worker. Claimed routes are the standalone actions whose `path` is under
633
+ its prefix and the generated table routers mounted there. The edge mounts a
634
+ forwarder at the prefix. The tenant Worker mounts the namespace's gate file
635
+ (`src/routes/__namespace-<name>.routes.ts`) and, behind it, every route the
636
+ namespace claims. A tenant feature's action under the prefix may sit outside
637
+ its feature's own path (`TENANCY_ROOT_ACTION` doesn't apply to it).
638
+
639
+ The edge routes a namespace request by the prefix's first `:param`, through
640
+ the tenant-backed kind whose `requestField` it is:
641
+
642
+ | Caller | Tenant |
643
+ |---|---|
644
+ | Instance-bound token of the kind | The tenant it pins (`ctx.oauth.boundTo.tenantId`). No lookup. A token for another instance: `403`. |
645
+ | Anyone else | `tenancy.lookups.<kind>` for the id. Several organizations: `409 TENANT_AMBIGUOUS`. No row: the same `403 ACCESS_ROLE_REQUIRED` the gate gives a caller who proves no lane, so an unknown id and an id you can't reach look alike. A new instance is indexed after its write, so it can answer that `403` briefly; retry. A failed lookup read: `503 TENANT_UNAVAILABLE`. |
646
+
647
+ The edge matches the prefix on the percent-decoded path Hono routes on, and
648
+ the bound-token confinement uses the same path, so an encoded variant
649
+ (`/api/v1/%65vent/…`) is routed and confined exactly like the plain one. A
650
+ request that reaches the namespace mount but matches no namespace is `404`; it
651
+ never falls through to active-organization routing. An encoded `/` (`%2F`)
652
+ stays encoded and is never an instance id. The caller's active organization
653
+ never routes a namespace request. A caller
654
+ whose active organization is a different one loses its organization seat and
655
+ its organization and team roles before the request is forwarded. Inside the
656
+ object, an organization firewall arm then matches only a member of this
657
+ organization; everyone else gets the rows their relationship proves.
658
+
659
+ In the object, the gate re-proves an instance-bound token with `admitLocal`,
660
+ the same program `qb.admitScope` runs. It uses the raw tenant SQLite, the
661
+ request's restore permit epoch, and the token's exact subject and proving
662
+ table. No RPC and no D1 read. The token's tenant must be the object's, and
663
+ its epoch the permit's: a token issued before a restore gets `403`, so the
664
+ user reauthorizes. A session caller passes a lane only as the subject
665
+ admission would choose: after the lane matches, the gate runs `admitLocal` in
666
+ discover mode and requires the same row. So the kind's precedence decides,
667
+ and two rows on the choosing role deny (`403`), exactly as at authorize. Then the relationship lanes, `loads` hydration (through the
668
+ loaded table's firewall) and the per-lane scope refresh run against tenant
669
+ SQLite exactly as on a single Worker. A namespace request costs one RPC (the
670
+ forward) plus, for a session caller, one lookup read in D1.
671
+
672
+ A claimed table's [legacy forward](/define/areas#keeping-the-old-url-legacy)
673
+ (`legacy`) is not a namespace route. The edge routes its old URL
674
+ (`/api/v1/locations`) by **active organization**, exactly as it routed the
675
+ table before the claim: a caller with no organization gets `400 TENANT_REQUIRED`
676
+ at the edge, and the organization object is always the caller's own, so the
677
+ §2a strip never applies. The forward runs in the tenant Worker
678
+ (`src/routes/__legacy-<feature>.routes.ts`, mounted beside the namespace),
679
+ requires `ctx.activeOrgId === ctx.tenantId`, reads the instance and any row from
680
+ tenant SQLite, and dispatches in-process to the namespace route: no second RPC.
681
+
682
+ A namespace that can't run in one place fails the build:
683
+
684
+ | Code | Cause |
685
+ |---|---|
686
+ | `TENANCY_NAMESPACE_SPLIT` | Its lanes, `loads` tables or claimed routes mix tenant and platform. |
687
+ | `TENANCY_NAMESPACE_PARTITIONED` | One of them is in a [partition](#partitions) object. |
688
+ | `TENANCY_NAMESPACE_UNROUTED` | It runs in tenant objects, but its `:param` is no scope kind's `requestField`, or a platform kind's, so a request can't name its organization. |
689
+ | `TENANCY_NAMESPACE_MINT` | It declares `mintScope` or `acceptScope` for a tenant-backed kind. |
690
+
691
+ #### Edge namespace actions
692
+
693
+ A tenant namespace's routes run in the tenant Worker, which has no `env`
694
+ bindings, secrets or Better Auth. An action under the prefix that needs them
695
+ (presigning an R2 upload, creating a Better Auth user, sending email) declares
696
+ `edge: true`. It keeps its URL and runs on the edge Worker:
697
+
698
+ {/* doc-compile: skip — needs a tenant namespace, a result job and a secret */}
699
+ ```ts title="quickback/features/uploads/actions/uploadUrl.ts"
700
+ import { z } from "zod";
701
+ import { defineAction, ActionError } from "../.quickback/define-action";
702
+ import { callTenantJob } from "../../../lib/tenants";
703
+
704
+ export default defineAction({
705
+ description: "A presigned upload URL for one event.",
706
+ path: "/event/:eventId/upload-url",
707
+ method: "POST",
708
+ edge: true,
709
+ input: z.object({ filename: z.string().min(1).max(200) }),
710
+ access: { roles: ["scope:event:staff", "scope:event:attendee"] },
711
+ async execute({ ctx, env, input }) {
712
+ const eventId = ctx.admittedInstance?.kind === "event" ? ctx.admittedInstance.id : undefined;
713
+ if (!eventId || !ctx.tenantId) throw new ActionError("No admitted event", "BAD_REQUEST", 400);
714
+ // Tenant data only through a result job, in the tenant the gate admitted.
715
+ const res = await callTenantJob<{ name: string }>(env, ctx.tenantId, { type: "event.name", eventId }, "event-name:" + crypto.randomUUID());
716
+ if (res.status !== "ok") throw new ActionError("Try again shortly", "EVENT_UNAVAILABLE", 503);
717
+ return { url: await presign(env.UPLOAD_SIGNING_KEY, `${ctx.tenantId}/${eventId}/${input.filename}`), event: res.result.name };
718
+ },
719
+ });
720
+ ```
721
+
722
+ The edge mounts these actions at the namespace prefix ahead of the forwarder,
723
+ each behind a gate on its own route. Every other route under the prefix is
724
+ forwarded as before. The gate reads no table. One `qb.admitScope` in the
725
+ instance's tenant decides:
726
+
727
+ | Caller | Admission |
728
+ |---|---|
729
+ | Instance-bound token of the kind | Exact admission of its subject in the tenant and epoch it pins. A revoked subject, or a token issued before a restore, gets `403`. A token for another instance gets `403`. |
730
+ | Session | The tenant from `tenancy.lookups.<kind>`, never the active organization, then discover admission under that tenant's current epoch: the namespace's relationship lanes, chosen by the kind's precedence. |
731
+ | Session, `{ roles }` lane | A member of that organization holding one of the lane's roles, when the tenant confirms the instance exists there and the user proves no row (`SCOPE_NO_ROLE`). Members of other organizations never qualify. |
732
+
733
+ Every denial, including an unknown or not-yet-indexed id, is the namespace's
734
+ `403 ACCESS_ROLE_REQUIRED`. A tenant that can't answer is `503` with
735
+ `Retry-After`, never a denial. On success `ctx.tenantId` is the admitted
736
+ tenant and `ctx.admittedInstance` is `{ kind, id }` for the admitted instance.
737
+ This routing metadata grants no scoped roles. Relationship admission also sets
738
+ `ctx.scope.<kind>` to the admitted entry (`id`, `roles`, `subjectId`,
739
+ `provingTable`); the organization-role lane clears that scope entry. A caller who isn't a member of that organization loses its
740
+ organization seat and roles, as on forwarded requests. Then the action's own
741
+ `access` runs against that `ctx`.
742
+
743
+ An edge action is a platform action:
744
+
745
+ - It lives in a platform feature. A feature with no tables is simplest. The
746
+ file location doesn't change its URL. In a tenant feature the build fails
747
+ with `TENANCY_EDGE_ACTION_PLACEMENT`.
748
+ - Its `db` is the platform D1. It reads tenant data through [result
749
+ jobs](#result-jobs) called with `ctx.tenantId`. Naming a tenant table, or
750
+ importing a tenant feature's module, fails the build
751
+ (`TENANCY_ADMISSION_DEPENDENCY`).
752
+ - The namespace's `loads` hydration never runs on the edge. Reading
753
+ `ctx.<exposeAs>` fails the build (`TENANCY_EDGE_ACTION_CTX`). Use
754
+ `ctx.scope.<kind>`, or read the row with a result job.
755
+ - Its path must be under a tenant namespace's prefix
756
+ (`TENANCY_EDGE_ACTION_NAMESPACE`). Without `edge: true`, a platform action
757
+ there splits the namespace (`TENANCY_NAMESPACE_SPLIT`).
758
+
759
+ Security notes:
760
+
761
+ - The gate proves the caller holds a role on the instance when the request
762
+ starts. A result job runs later, with system rights, in a separate
763
+ transaction. A revocation can land between the two. When a write must be
764
+ authorized atomically with the authorization, recheck the subject inside the
765
+ job (its message carries `ctx.scope.<kind>.subjectId`), or keep the write in
766
+ a tenant action behind the tenant gate.
767
+ - The job's tenant must be `ctx.tenantId`. Never use an id from the request
768
+ (`TENANCY_JOB_CALL_TENANT_SOURCE`). Scope any job input by the admitted
769
+ instance (`ctx.scope.<kind>.id`).
770
+ - Each request costs one `qb.admitScope` RPC, plus a lookup read and a
771
+ `qb.epoch` RPC for a session caller.
772
+
773
+ In shared mode (no `isolation: 'durable-object'`), `edge` has no effect. The
774
+ namespace already runs on the edge.
775
+
776
+ ## Requests
777
+
778
+ | Request | Result |
779
+ |---|---|
780
+ | Tenant route, active organization set | Forwarded to that organization's object |
781
+ | Tenant route, no active organization | Resolved through a [lookup](#lookup-indexes) named after the token's scope kind; otherwise `400 TENANT_REQUIRED`. Several matching organizations: `409 TENANT_AMBIGUOUS`. |
782
+ | [Tenant namespace](#tenant-namespaces) route | A bound token: the tenant it pins. Anyone else: the kind's lookup for the `:param` (`409 TENANT_AMBIGUOUS`; an unknown id gets the gate's own `403`). Never the active organization. |
783
+ | Partitioned route | Forwarded to the partition's object; see [Partitions](#partitions) for `PARTITION_KEY_REQUIRED` / `PARTITION_KEY_MISMATCH` |
784
+ | Tenant route, unauthenticated | `401 AUTH_MISSING` |
785
+ | Platform route | Served by the edge from D1 |
786
+ | Tenant object whose migration failed | `503 TENANT_MIGRATION_FAILED` with the migration tag and SQLite error in `details.error` (never the SQL) |
787
+ | Archived tenant | `423 TENANT_ARCHIVED` (checked inside the object, no D1 read) |
788
+ | Purged tenant | `410 TENANT_PURGED` |
789
+ | Body larger than 1 MiB (`Content-Length`) | `413 PAYLOAD_TOO_LARGE` at the edge |
790
+ | Tenant object reset, or a retryable RPC error | `GET` / `HEAD`: retried once on a fresh stub. Anything else is sent once. Then `503 TENANT_UNAVAILABLE` with `Retry-After`. The registry is not touched. |
791
+ | Tenant object overloaded | `503 TENANT_OVERLOADED` with `Retry-After`. Never retried. |
792
+ | Subrequest depth limit exceeded | `508 TENANT_DEPTH_EXCEEDED` |
793
+ | Any other RPC error | `503 TENANT_UNAVAILABLE`; rows without an ordered health report become `migrating` with the error. An existing ordered health report is preserved. |
794
+
795
+ ### Same-tenant unsafe actions
796
+
797
+ A tenant feature may declare `unsafe: { reason, crossTenant: false }`. The
798
+ action runs in the tenant object like any other, with the same access checks
799
+ and security wrapper as on the edge:
800
+
801
+ - `unsafeDb` is the object's own SQLite, without the firewall. It can't reach
802
+ the D1, the auth database or another organization: those are not in the
803
+ object.
804
+ - `unsafeDb.scopeTo({ organizationId })` accepts only the object's own
805
+ organization. Any other throws `TENANT_SCOPE_MISMATCH` (403).
806
+ - Cross-tenant `unsafe` (`unsafe: true`, or an object without
807
+ `crossTenant: false`) and `unsafe.authWrites` are refused
808
+ (`TENANCY_UNSAFE_ACTION`). The `ctx` and `env` checks still apply
809
+ (`TENANCY_CTX_UNAVAILABLE`, `TENANCY_ENV_UNAVAILABLE`).
810
+
811
+ ## Transactions
812
+
813
+ Inside a tenant object, `db.transaction(cb)` is
814
+ `ctx.storage.transactionSync()`. Only statements that run before `cb` returns
815
+ are in the transaction. Every action helper of a tenant feature types `db` and
816
+ `unsafeDb` as that synchronous handle: `define-action.ts`, the per-table
817
+ `define-action.<table>.ts` and the namespace `define-action.<scope>.ts`.
818
+ Do all I/O first, then pass a synchronous callback:
819
+
820
+ {/* doc-compile: skip — action body fragment */}
821
+ ```ts
822
+ const rows = await db.select().from(projects);
823
+ await db.transaction((tx) => {
824
+ for (const row of rows) {
825
+ tx.update(projects).set({ name: "x-" + row.name }).where(eq(projects.id, row.id)).run();
826
+ }
827
+ });
828
+ ```
829
+
830
+ The callback's return type is checked: returning a PromiseLike is a type
831
+ error — an `async` callback, a Promise, a union containing one
832
+ (`flag ? work(tx) : undefined`), or a query builder not yet executed (builders
833
+ are thenable; end every statement in `.run()`, `.all()`, `.get()` or
834
+ `.values()`). Returning `any` is refused too, because it can hide a Promise:
835
+ annotate the helper's return type. An awaited body runs after the transaction
836
+ has committed, so nothing after the first `await` would roll back.
837
+
838
+ The build backs the type for code that casts it away (`(db as any)`): on a
839
+ `transaction(...)` call on a db or tx handle, an `async` callback, or one that
840
+ returns or starts a Promise (`await`, `Promise.*`, `.then`), fails with
841
+ `TENANCY_ASYNC_TRANSACTION`. Put `// quickback-allow-transaction` on the call's
842
+ line, or the line above, to opt one call out.
843
+
844
+ Batch handlers on tenant tables are transactional. `PATCH /batch` and
845
+ `PUT /batch` with `failFast: true` run in `ctx.storage.transaction()` and roll
846
+ back every write on failure (`meta.transactional: true`). See
847
+ [Batch operations](/api/batch-operations#transactional-semantics). That loop
848
+ awaits only tenant SQLite, so a tenant table's `create` / `update` / `upsert`
849
+ access and its `guards` must be declarative: a function there fails the build
850
+ (`TENANCY_BATCH_ASYNC`), because it could await other I/O and let another
851
+ request's writes interleave into the transaction.
852
+
853
+ ## Hard deletes and the audit log
854
+
855
+ The tenant Worker has no `AUDIT_DB`. A hard `DELETE` (single or batch) on a
856
+ tenant table writes its `audit_events` row to the object's outbox — in the
857
+ object's own SQLite, in one transaction with the delete, so a failed delete
858
+ leaves no audit row — and the response tells the edge to drain it. The edge
859
+ sets each row's `target_org_id` and `actor_org_id` to the object's organization
860
+ (tenant code cannot attribute a row to another one; a mismatch is logged and
861
+ kept in `metadata.tenantClaimed`), writes the rows to the audit database
862
+ (idempotent by id), then acknowledges them. Unacknowledged rows are retried
863
+ after the object's next response. A malformed audit payload moves to the
864
+ object's `__qb_outbox_dead` table instead of blocking the queue, and
865
+ `tenant_registry.outbox_dead_letters` counts them. Database failures leave rows
866
+ queued for retry; error messages never classify them as permanently invalid.
867
+ Purge first drains pending rows and copies dead letters into the audit database.
868
+ If either step fails, or pending rows remain, purge refuses to erase the object.
869
+ Purge is exclusive. It takes the control object's maintenance fence, which is
870
+ refused (`TENANT_BUSY`) while any request, job or alarm holds a permit,
871
+ including one waiting on I/O, so nothing writes into the object after it is
872
+ erased. `deleteAll()` erases any marker the object keeps itself, so purge then
873
+ turns that fence into a permanent `purged` marker in the object's control
874
+ object (`__qb_control__:<name>`, outside the tenant's storage). Only then does
875
+ it call `deleteAlarm()` and `deleteAll()`, and mark its own storage `purged`.
876
+ A reset anywhere in between leaves a tenant that is still purged, never a live
877
+ empty one:
878
+
879
+ - Every request, command, job, alarm and schedule takes a permit from the
880
+ control object, and the permit carries the marker. The object answers
881
+ `410 TENANT_PURGED`, and commands answer `unavailable` / `TENANT_PURGED`,
882
+ even while its own storage still says `archived`.
883
+ - On wake, an archived object asks its control object, and so does any object
884
+ that has not yet had one successful check. If the marker is there, the object
885
+ does not migrate: it marks itself `purged` and reports `tenant purged`. If the
886
+ control object cannot be read, the object migrates as usual and asks again
887
+ on its next wake. It still serves nothing, because its permits carry the
888
+ marker.
889
+ - Archive, unarchive, restore, cancel-restore, retry-migration, backups,
890
+ scheduling and lookup rebuilds all refuse a purged tenant.
891
+
892
+ `tenant_registry` still says `archived` after an interrupted purge. To recover,
893
+ retry `POST /tenants/:id/purge`. Purge is resumable: once the marker exists it
894
+ needs no fence, erases whatever is left, and marks the registry `purged`. The
895
+ retry keeps `last_purge_bookmark` from the first attempt and never records a
896
+ bookmark taken after the erase.
897
+
898
+ The marker is a control-object operation, not just a flag. Workers built before
899
+ it already refuse every permit and restore while an operation is set, so a mixed
900
+ deploy fails closed on it. Limits:
901
+
902
+ - During a gradual deploy, a control object still on the previous Worker cannot
903
+ record the marker. Purge then releases its fence and fails before it erases
904
+ anything; retry it once the deploy finishes.
905
+ - Do not purge while a tenant Worker rollout is in progress. An edge Worker on
906
+ the previous build reaching a tenant object on the previous build runs the
907
+ old, unmarked purge.
908
+ - Rolling the tenant Worker back to a build from before the purge marker
909
+ un-protects interrupted purges. The marker still refuses permits there, but
910
+ that build's `POST /tenants/:id/cancel-restore` treats it as an uncertain
911
+ restore and can clear it.
912
+
913
+ ## Migrations
914
+
915
+ Tenant tables have their own migrations in `quickback/drizzle/tenant/`. The
916
+ build bundles them into `quickback/drizzle/tenant/migrations.ts`, and each
917
+ object applies pending migrations when it wakes:
918
+
919
+ 1. Inside `blockConcurrencyWhile`, so no request runs against an old schema.
920
+ 2. All pending migrations in one transaction, recorded in `__qb_tenant_migrations`.
921
+ 3. A point-in-time-recovery bookmark is taken first and reported to
922
+ `tenant_registry.last_pre_migration_bookmark`.
923
+ 4. A failure never throws from the constructor. The object records it and
924
+ answers `503 TENANT_MIGRATION_FAILED` with the real SQLite error
925
+ (`0001_x: UNIQUE constraint failed: …`). The failing statement goes to the
926
+ logs and `tenant_registry.last_error`, never to the client. Other tenants
927
+ keep serving.
928
+ 5. Before migrating, the object records which migrations it is attempting
929
+ and flushes that record (`storage.sync()`). A wake that finds the same
930
+ attempt unfinished was preceded by a reset mid-migration — the 30 s
931
+ `blockConcurrencyWhile` limit, but also eviction, a deploy or a failover —
932
+ so it retries. After 3 resets of the same pending set the object marks
933
+ itself failed instead of retrying on every request. A different migration
934
+ set starts a fresh count; `POST <api>/tenants/:id/retry-migration` clears
935
+ the count and migrates again.
936
+
937
+ SQL triggers on tenant tables — your [`sql:` triggers](/define/triggers#tenant-databases)
938
+ and the compiler's own (the FK `match` checks) — install in the same wake, after
939
+ the migrations, whenever their content hash changes or a migration ran (a table
940
+ recreate drops its triggers). They never reach the features D1. A dump restore
941
+ drops every table with its triggers, loads the rows with no trigger firing, then
942
+ runs this same wake, so the triggers come back; a point-in-time restore rewinds
943
+ the triggers together with the data.
944
+
945
+ Keep wake work well under 30 s. The object never sets an alarm while
946
+ recovering, so a failing wake cannot reset the platform's alarm retry budget.
947
+
948
+ Restoring the bookmark discards writes made after it. It recovers a failed
949
+ migration; it is not a rollback.
950
+
951
+ The build refuses drizzle-kit table-recreate migrations on tenant tables
952
+ (`TENANCY_UNSAFE_RECREATE`) when the table is referenced by another table, or
953
+ when the copy targets a NOT NULL column that was nullable or has no DEFAULT.
954
+ Inside the migration transaction `PRAGMA foreign_keys=OFF` is a no-op, so the
955
+ recreate's `DROP TABLE` cascade-deletes child rows in every tenant. No
956
+ migration is written. Make the change additive (a new nullable column or a new
957
+ table, backfilled by a data migration) and rebuild.
958
+
959
+ Keep tenant schemas additive across one release: during a rollout, objects
960
+ still on the previous Worker version read the same tables.
961
+
962
+ ## Backups and restore
963
+
964
+ With `tenancy.backup` set, every tenant object backs itself up to R2 on its own
965
+ alarm. A write marks the object dirty and schedules the next backup `every`
966
+ later; an object nobody writes to runs no alarm and takes no backup. With
967
+ `every: 'off'` no dump is ever scheduled (a running one finishes and pending
968
+ ones are dropped on the next wake): point-in-time recovery (30 days) is then
969
+ the routine backup, and the bucket serves only operator backups, dump restores
970
+ and moving an organization between objects. A purge deletes the purged object's
971
+ dumps (the receipt-fenced one it was admitted with included): no copy outlives
972
+ the object except point-in-time recovery.
973
+
974
+ A backup is one NDJSON object at `<objectId>/<startedAt>-<uuid>.ndjson`: a header (the
975
+ object, its applied migrations, its tables), one line per row
976
+ (`{"t": table, "r": row}`, BLOBs as `{"$b64": …}`), and a footer with the row
977
+ count and the rows per table (`{"qb": "end", "rows": n, "counts": { table: n }}`;
978
+ every table in the header appears, empty ones as `0`). A dump restore checks
979
+ them before it touches anything: per-table counts that disagree with the rows
980
+ (either way) or do not add up to `rows` refuse the dump. Dumps written
981
+ before this footer gained `counts` have only `rows`. It streams in steps: each alarm reads tables in `rowid` order, uploads
982
+ R2 multipart parts of exactly 5 MiB (only the last part is smaller), and keeps
983
+ the leftover bytes and the `(table, rowid)` cursor in object-local storage, so
984
+ the next step resumes where the last stopped. When it finishes, the edge
985
+ records `tenant_registry.last_backup_at` / `last_backup_key` from the object's
986
+ outbox, and dumps older than `retainDays` are deleted.
987
+
988
+ An active tenant’s backup is **not a point-in-time snapshot**: rows written while it runs may
989
+ or may not be in it. For an exact copy, restore a point-in-time bookmark.
990
+
991
+ | Operator route | Effect |
992
+ |---|---|
993
+ | `POST /tenants/:id/backup` | Take a full backup now; returns `{ key, rows, counts, bytes, parts, startedAt, finishedAt, generation, archived }` |
994
+ | `GET /tenants/:id/backups` | List the object's dumps |
995
+ | `GET /tenants/:id/backups/counts?key=<key>` | One dump's footer, `{ key, rows, counts }`, from a single bounded read of the dump's last 256 KiB (the dump is never loaded). `counts` is `null` for a dump written before footers carried it. A key of another object is refused (`400 TENANT_BACKUP_READ_INVALID`), a missing dump is `404 TENANT_BACKUP_NOT_FOUND`. A tenant Worker older than this route answers `TENANT_RPC_VERSION_MISMATCH`: deploy the tenant Worker first. Also `tenantBackupCounts(env, id, key)` in `src/lib/tenants.ts`. |
996
+ | `GET /tenants/:id/bookmark` | The object's exact current point-in-time bookmark, `{ bookmark, observedAt }`. Record it before a risky change; restoring `{ "bookmark": "…" }` returns to exactly this point (never restore `{ at: observedAt }`, which is approximate). Refused for a purged object, or one whose purge is under way (its last bookmark is `tenant_registry.last_purge_bookmark`). |
997
+ | `GET /tenants/:id/outbox-receipts` | [Delivery receipts](#delivery-receipts): `?since=&limit=&outcome=` |
998
+ | `POST /tenants/:id/schedules/arm` `{ "types"?: [...] }` | Re-arm the organization's [tenant schedules](#tenant-schedules) (all, or the given job types); each runs after its debounce unless due sooner. Registered organization objects only. Returns `{ armed }`. `POST /tenants/schedules/arm-all` does every registered organization (bounded concurrency) — a manual one-off after a deploy, never a cron. |
999
+ | `POST /tenants/lookups/migrate` `{ "limit"?: n }` | With a [hashed lookup](#hashed-lookups): convert one page of pre-hash rows across objects. Returns `{ rekeyed, remaining }`; repeat until `remaining` is false. |
1000
+ | `POST /tenants/:id/rebuild-lookups` | Delete the object's platform lookup rows and re-publish every current key from its rows, under the primary `TENANT_LOOKUP_KEY` (after a [rotation](#hashed-lookups)). Its keys may not resolve until the drain finishes. Returns `{ applied }`. |
1001
+ | `POST /tenants/:id/restore` `{ "backupKey": "…" }` | Archived objects only. Restore a dump: drop every tenant table, re-create the schema at the dump's migrations, load its rows (one transaction), then apply the migrations added since. An old dump comes forward to the current schema. Refuses a dump from another object, a truncated dump, or one taken at migrations this Worker does not know. Returns `{ kind: "dump", backupKey, rows, pending: true }`; the object restarts and stays archived. Pending scheduled jobs are dropped (see [restore quarantine](#restore-quarantine)). |
1002
+ | `POST /tenants/:id/restore` `{ "bookmark": "…" }` or `{ "at": <ms or ISO> }` | Archived objects only. Point-in-time recovery (30 days): `onNextSessionRestoreBookmark`, then the object restarts. Writes after the bookmark are discarded. Returns `{ kind: "pitr", bookmark, undoBookmark, pending: true }`. A bookmark is exact. `at` is resolved with `getBookmarkForTime`, which Cloudflare documents as *approximate*: on a real deployment, writes made a few seconds before `at` were missing after the restore. For a precise target use `GET /tenants/:id/bookmark` beforehand, or the `undoBookmark` of an earlier restore. |
1003
+
1004
+ An operator backup on an **archived** organization acquires exclusive maintenance
1005
+ admission before scanning. It refuses with `TENANT_BUSY` while older requests,
1006
+ jobs or alarms still hold permits, abandons an unfinished active scan, and
1007
+ starts a fresh one while blocking unarchive, restore and purge. Its completed
1008
+ receipt has `archived: true` and the current `generation`. Active and scheduled
1009
+ backups have `archived: false` and retain the incremental behavior above.
1010
+
1011
+ ### Reading a completed backup in operator application code
1012
+
1013
+ `readTenantBackup` from `src/lib/tenants.ts` transports the latest completed,
1014
+ quiescent backup through the tenant Worker. The backup bucket remains bound
1015
+ only to that Worker. No download HTTP route, arbitrary SQL, archived tenant-job
1016
+ admission or edge bucket access is added. Call this helper only after your
1017
+ application verifies the operator and target organization; it does not perform
1018
+ HTTP authentication itself, like the other operator helpers.
1019
+
1020
+ After `archiveTenant` and `backupTenant`, pass only the receipt's `key`,
1021
+ `generation` and `bytes` to
1022
+ `readTenantBackup(env, organizationId, { key, generation, bytes })`.
1023
+ The result is `{ key, generation, bytes, etag, data }`, with `data` an
1024
+ `ArrayBuffer` of the original encoded NDJSON. Use `new TextDecoder().decode(data)`
1025
+ only after the helper succeeds, then validate and project the application data
1026
+ you intend to retain. Keep raw dumps private; a dump contains all tenant tables.
1027
+
1028
+ The hard whole-buffer limit is **8 MiB of encoded bytes**. Optional `maxBytes`
1029
+ may lower that limit, never raise it. A larger dump fails with
1030
+ `TENANT_BACKUP_READ_TOO_LARGE`; it is not truncated. Do not purge a tenant when
1031
+ retention fails. Larger exports need a future bounded streaming protocol.
1032
+
1033
+ The helper requires the exact latest completed receipt, an archived organization,
1034
+ a matching current generation, and no writes since that backup. Old receipts,
1035
+ active backups, foreign keys, partition/control objects, changed byte lengths
1036
+ and malformed replies refuse. Legacy receipts without the new fields require a
1037
+ fresh archived backup. The tenant checks R2 metadata and the actual stream length,
1038
+ then returns binary bytes rather than base64 or a result-job JSON payload.
1039
+ Exclusive maintenance remains held through the body read: pending restore or
1040
+ purge refuses the read, and restore, purge or unarchive cannot begin during it.
1041
+ The edge checks the registry before and after the RPC; application workflows must
1042
+ still recheck their maintenance fingerprint before a later destructive operation.
1043
+
1044
+ This helper needs tenant RPC version 7. Deploy the tenant Worker before the edge
1045
+ Worker; an older tenant Worker cannot supply the new operation. A failed or
1046
+ ambiguous maintenance release keeps the existing recovery fence, requiring
1047
+ operator reconciliation rather than silently reopening admission.
1048
+
1049
+ The same operations are `backupTenant`, `listTenantBackups` and `restoreTenant`
1050
+ in `src/lib/tenants.ts`. Dump restore has an **8 MiB encoded NDJSON limit**
1051
+ (`413 TENANT_RESTORE_TOO_LARGE`), checked before reading the body or changing
1052
+ any table. Larger dumps need PITR until streaming restore is implemented.
1053
+ Restore cancels any in-progress multipart upload, clears its cursor and carry,
1054
+ and schedules a fresh backup. Both restore kinds and migration retry acquire exclusive
1055
+ admission before reading R2 or changing data. They refuse with `TENANT_BUSY`
1056
+ while previously admitted HTTP handlers, deferred `waitUntil` work (including
1057
+ nonblocking after-commit hooks and `effects.enqueue` callbacks), jobs, alarms or
1058
+ backup work remain in flight. HTTP responses return before nonblocking effects
1059
+ settle; their admission permits remain held through nested deferred work and
1060
+ release after success or rejection. Retry after that work finishes. New work is quarantined while the
1061
+ operation runs; a known success or failure releases its matching gate. An
1062
+ ambiguous operation or failed release retains quarantine for explicit operator
1063
+ recovery. Backup and restore operations are serialized.
1064
+
1065
+ Use `effects.enqueue`, nonblocking `afterCommit` hooks or
1066
+ `c.executionCtx.waitUntil(...)` for deferred tenant work. Authored access to the
1067
+ raw `waitUntil` export of `cloudflare:workers` is refused with
1068
+ `TENANCY_UNTRACKED_BACKGROUND` in tenant modules and their statically named
1069
+ relative authored dependencies, including aliases and helper re-exports that
1070
+ bypass the request's tracker. This includes a dynamic import's ordinary
1071
+ fulfillment callback reading the namespace through implicit `arguments[0]`,
1072
+ even when its declared parameter is unused or the access is in a nested arrow.
1073
+ Uninspectable argument or namespace escapes fail closed. Unrelated Cloudflare
1074
+ exports remain available when their access is explicit. External packages, path
1075
+ aliases and computed module names are outside this source-level check. Keep
1076
+ unrelated Cloudflare imports; use the
1077
+ tracked context instead of importing `waitUntil`. Await database work that must
1078
+ finish before the response. Arbitrary promises or timers launched without
1079
+ `await` or a tracked scheduler are outside this lifetime contract; do not retain
1080
+ a tenant database handle in them.
1081
+ A failed upload keeps its checkpoint and retries; writes during a backup
1082
+ schedule another backup after it completes.
1083
+
1084
+ ### Restore quarantine
1085
+
1086
+ Every restore, dump or point-in-time, follows the same steps:
1087
+
1088
+ 1. `POST /tenants/:id/archive`. A restore of an object that is not archived is
1089
+ refused (`tenancy: archive before restore`), as is a restore while an
1090
+ earlier one is pending (`TENANT_RESTORE_PENDING`).
1091
+ 2. `POST /tenants/:id/restore`. It returns `pending: true`; the object restarts.
1092
+ 3. `POST /tenants/:id/sync` reconciles the restore under a new outbox
1093
+ generation. The object is still archived.
1094
+ 4. Inspect it, then `POST /tenants/:id/unarchive`. Nothing serves a restored
1095
+ object before this explicit step. Unarchive refuses
1096
+ (`TENANT_RESTORE_PENDING`) until step 3 has reconciled the restore, or while
1097
+ an unconfirmed restore or stranded maintenance fence is open — clear those
1098
+ with `POST /tenants/:id/cancel-restore`.
1099
+
1100
+ A dump carries no schedule: dump restore drops the object's pending scheduled
1101
+ jobs (`scheduleTenantJob`), its job-run dedupe records and its queued non-audit
1102
+ outbox entries in the same transaction as the load, so nothing scheduled
1103
+ against the replaced rows fires against the restored ones. Reschedule
1104
+ recurring work after unarchive. PITR instead rewinds the schedule to the
1105
+ bookmark with the rest of the database.
1106
+
1107
+ Restore first acquires an external admission
1108
+ gate: a small control object in the existing tenant namespace, under a reserved
1109
+ `__qb_control__:` name. The gate is outside the database being rewound. It
1110
+ refuses restore while requests or outbound jobs are in flight, then quarantines
1111
+ handlers, jobs and alarms until reconciliation. Control objects use the class's
1112
+ implicit `ctx.exports` namespace; no extra namespace or binding is provisioned.
1113
+ A tenant object does not ask its control object per request: it keeps the
1114
+ permit it was last granted as a lease and admits its own requests, jobs and
1115
+ alarms under it with no control RPC. The lease is an ordinary permit, so the
1116
+ gate still refuses restore while it is held. Restore, purge, migration retry
1117
+ and archived backups first revoke it: refused (`TENANT_BUSY`) while any work
1118
+ admitted under it (deferred callbacks included) is still running; otherwise
1119
+ the lease is released, and none is granted again until the fence is released.
1120
+ A lease admits work for at most 30 seconds; the next admission after that
1121
+ re-validates with the control object. An idle lease stays registered until it
1122
+ is revoked or replaced, so a control object reports `TENANT_BUSY` to any
1123
+ caller that skips the object's own revocation. A restart or eviction leaves
1124
+ its permit behind; the object's next admission, or the next restore's prune,
1125
+ removes it. Cross-object work (an outbox job from another
1126
+ object) still takes and releases the source object's permit per delivery.
1127
+
1128
+ Restore fences the old outbox generation and removes platform lookup rows.
1129
+ After a confirmed restore restarts the object, call `POST /tenants/:id/sync` to
1130
+ rebuild lookups under the new generation. Reconciliation discards the queued
1131
+ outbox entries other than audit rows and scope revocations, because they
1132
+ describe writes the restore replaced (a dump restore already dropped them with
1133
+ the load). A queued revocation is kept: rolling data back never un-revokes a
1134
+ claim. A dump restore is confirmed once its load commits; a dump that is
1135
+ refused (too large, truncated, another object's) changes nothing and releases
1136
+ quarantine like a rejected PITR prepare. `TENANT_RESTORE_PENDING` means the
1137
+ operation is unconfirmed or the old session has not restarted. A rejected
1138
+ prepare releases quarantine and restores its old lookup index. An unrelated
1139
+ restart never turns an unconfirmed prepare into a successful restore.
1140
+
1141
+ For an uncertain operation, inspect the current state and explicitly call
1142
+ `POST /tenants/:id/cancel-restore` with `{ "confirm": "<objectId>" }`. If the
1143
+ old session is still running, this first restarts it and returns pending; repeat
1144
+ the explicit recovery call after restart. Recovery keeps the current database
1145
+ and queued work, rebuilds lookups, and stays archived. A failed pre-invocation
1146
+ rollback resumes its recorded cleanup instead. Recovery owns one persisted
1147
+ mode so delayed cleanup cannot race abandonment. Once abandonment is claimed a
1148
+ restore can no longer be armed, but one that took effect anyway (a PITR
1149
+ bookmark is irreversible once scheduled; a dump load committed) is recorded in
1150
+ the control object: abandonment then discards queued non-audit outbox entries
1151
+ like a confirmed restore and returns `applied` (`{ bookmark, undoBookmark }` or
1152
+ `{ backupKey, rows }`; `null` when nothing applied). A restore whose arming RPC
1153
+ was lost before it reached the control object cannot be recorded; such an
1154
+ abandonment keeps queued work. A completed restore also stays archived;
1155
+ inspect it before `POST /tenants/:id/unarchive`. Never automatically retry the
1156
+ restore write.
1157
+
1158
+ ### Authorization epoch
1159
+
1160
+ The control object also holds an **authorization epoch**, a counter that no
1161
+ restore can rewind. It is per object name: an organization object and each of
1162
+ its partition objects have their own. Every restore, dump or PITR, advances it
1163
+ when the restore begins, and keeps it across success, rollback and abandonment.
1164
+ Read it with `tenantAuthorizationEpoch(env, objectId)` in `src/lib/tenants.ts`
1165
+ (or the object's `authorizationEpoch` RPC), or with the
1166
+ [`qb.epoch` command](#tenant-commands), which reads it under the restore permit.
1167
+
1168
+ The epoch is exposed for admission checks; nothing enforces it yet. Enforcement
1169
+ arrives with tenant admission (plan 032): credentials pinned to an earlier
1170
+ epoch will then be refused, so a restore forces re-login even when restored
1171
+ rows would grant the old access again. Restore does not call `/oauth2/revoke`.
1172
+
1173
+ Point-in-time recovery does not run under local `wrangler dev`. The staging
1174
+ account drill remains an open release gate: write A, note time T, write B,
1175
+ archive, restore to T, sync after restart, and verify A remains, B is gone,
1176
+ lookup entries match the restored rows, and scheduled work resumes safely.
1177
+ Do not treat the local reconciliation simulation as a completed PITR drill. The R2 dump/restore drill runs locally in the
1178
+ `tenant-do` output-matrix fixture.
1179
+
1180
+ ## Background work
1181
+
1182
+ Per-tenant alarms replace global "every minute, scan every organization"
1183
+ sweeps. Each object has one alarm, shared by backups and tenant jobs, driven by
1184
+ a schedule table: a due row is moved to its retry time before the work runs,
1185
+ and a finished occurrence is recorded before its row is removed, so a crash
1186
+ retries the same occurrence up to five attempts. Handlers must make external
1187
+ side effects idempotent. Canceling or replacing a due occurrence prevents its
1188
+ stale snapshot from running; rescheduling at the same time creates a new
1189
+ occurrence. Unarchiving re-arms suspended work.
1190
+
1191
+ A **tenant job** is a `services/queues` handler that runs inside a tenant
1192
+ object. Mark it `tenant: true` (implied when it imports an unpartitioned tenant
1193
+ feature). A handler may not mix platform and tenant imports; a feature with no
1194
+ tables (helpers only) is neither, so either kind may import it. Partitioned
1195
+ feature imports are refused until explicit partition queue routing is supported.
1196
+ Inside a tenant job, `tenant` on the execute context supplies scheduling,
1197
+ cancellation and outbox delivery; it is absent for platform handlers.
1198
+
1199
+ {/* doc-compile: skip — needs a reminders feature */}
1200
+ ```ts title="quickback/services/queues/reminderDue.ts"
1201
+ import { eq } from "drizzle-orm";
1202
+ import { defineQueue } from "@quickback/compiler";
1203
+ import { reminders } from "../../features/reminders/schema";
1204
+
1205
+ export default defineQueue<{ type: "reminder.due"; tenantId: string; reminderId: string }>({
1206
+ name: "reminderDue",
1207
+ messageType: "reminder.due",
1208
+ tenant: true,
1209
+ execute: async ({ message, db }) => {
1210
+ db.update(reminders).set({ sentAt: new Date().toISOString() }).where(eq(reminders.id, message.reminderId)).run();
1211
+ return { success: true };
1212
+ },
1213
+ });
1214
+ ```
1215
+
1216
+ The same handler runs three ways:
1217
+
1218
+ | Trigger | How |
1219
+ |---|---|
1220
+ | Queue | A producer sends `{ type, tenantId, … }`; the edge consumer routes it to that tenant's object (`runJob`). A message literal for a tenant job without `tenantId` fails the build (`TENANCY_QUEUE_TENANT_ID`); at runtime one without it is retried into the dead-letter queue. |
1221
+ | Alarm | `tenantRuntime(env).schedule(key, at, message)` from a tenant action or job, or `scheduleTenantJob(env, tenantId, key, at, message)` on the edge. One pending occurrence per key; a job reschedules its own key for the next due item. |
1222
+ | Outbox | `tenantRuntime(env).send(target, message)` — see [Partitions](#partitions). |
1223
+ | Platform queue | A tenant action or job calls `tenantRuntime(env).enqueue(binding, message)`; the edge sends it to a platform queue and that queue's consumer routes it — see [Platform queues](#platform-queues). |
1224
+
1225
+ Tenant actions import `tenantRuntime` from their `define-action` helper:
1226
+
1227
+ {/* doc-compile: skip — action body fragment */}
1228
+ ```ts
1229
+ await tenantRuntime(env).schedule("reminder:" + row.id, Date.parse(row.remindAt), { type: "reminder.due", reminderId: row.id });
1230
+ ```
1231
+
1232
+ `schedule`, `send` and the edge helpers stamp `tenantId`. Each run gets a
1233
+ `runId`, stable per occurrence or message: use it as the idempotency key for
1234
+ external side effects (email, SMS, payments).
1235
+ Concurrent deliveries of one `runId` share an in-flight execution in the live
1236
+ object. Completion is recorded only on success. A crash after an external effect
1237
+ but before durable completion can repeat that effect: delivery remains
1238
+ at-least-once, so handlers must use that idempotency key externally.
1239
+
1240
+ Tenant jobs honor `ack()` and `retry()` for queues, alarms and outbox delivery.
1241
+ `retry()` is sticky and wins over a later `ack()` or a successful return; no
1242
+ completion marker is recorded for that attempt.
1243
+
1244
+ After an alarm, the object asks its edge to drain what the alarm left in the
1245
+ outbox (queue sends, realtime, lookups) through the edge's
1246
+ `QuickbackTenantOutbox` entrypoint — the tenant Worker binds it as
1247
+ `__QB_EDGE_OUTBOX` (generated in `wrangler.tenant.jsonc`, each target its own
1248
+ edge). While entries remain (the edge unreachable, entries backing off), an
1249
+ internal alarm asks again — after 30 s, doubling to an hour while a drain
1250
+ makes no progress — so delivery never waits for the tenant's next request and
1251
+ no cron sweeps the objects. Without the binding it does not poll: the next
1252
+ request or operator sync drains. A named entrypoint is reachable only through
1253
+ a service binding, never over HTTP; tenant app code does not see the binding,
1254
+ and the edge drains only registered objects (an unknown name is refused, never
1255
+ woken). Keys starting `qb:` (`qb:backup`, `qb:outbox-flush`,
1256
+ `qb:schedule:<type>`) belong to the runtime: `schedule` / `cancel` and the edge
1257
+ helpers refuse them (`TENANT_JOB_INVALID`).
1258
+
1259
+ An alarm that throws retries the same occurrence with backoff (10 s, doubling,
1260
+ capped at an hour). After five attempts it is a **dead letter**: a `failed`
1261
+ [delivery receipt](#delivery-receipts) of kind `alarm` (`target` the key,
1262
+ `method` the job type, `reason` `TENANT_ALARM_DEAD_LETTER: …` with the last
1263
+ error). A one-off occurrence is then dropped; a [tenant
1264
+ schedule](#tenant-schedules) runs again an hour later, and writes to its
1265
+ watched tables do not bring that retry forward.
1266
+
1267
+ ### Tenant schedules
1268
+
1269
+ A **tenant schedule** is recurring per-tenant work with no cron and no global
1270
+ scan: a tenant job with `schedule:`, run on each organization's own alarm. It
1271
+ runs when it is due and returns `next` — when it is due again (ms or a
1272
+ `Date`), or `null` to sleep. An organization with nothing due never wakes.
1273
+
1274
+ {/* doc-compile: skip — needs a reminders feature */}
1275
+ ```ts title="quickback/services/queues/remindersTick.ts"
1276
+ import { and, eq, isNull, lte, min } from "drizzle-orm";
1277
+ import { defineQueue } from "@quickback/compiler";
1278
+ import { reminders } from "../../features/reminders/schema";
1279
+
1280
+ export default defineQueue<{ type: "reminders.tick"; tenantId: string }>({
1281
+ name: "remindersTick",
1282
+ messageType: "reminders.tick",
1283
+ tenant: true,
1284
+ // Writes to these tables (any request, job or alarm) re-arm it.
1285
+ schedule: { watch: ["reminders"], debounceSeconds: 5 },
1286
+ execute: async ({ db, tenant, runId, schedule }) => {
1287
+ const now = new Date().toISOString();
1288
+ for (const r of await db.select().from(reminders).where(and(isNull(reminders.sentAt), lte(reminders.dueAt, now)))) {
1289
+ db.update(reminders).set({ sentAt: now }).where(eq(reminders.id, r.id)).run();
1290
+ tenant!.enqueue("EMAIL_QUEUE", { type: "reminder.send", reminderId: r.id });
1291
+ }
1292
+ const [next] = await db.select({ at: min(reminders.dueAt) }).from(reminders).where(isNull(reminders.sentAt));
1293
+ return { success: true, next: next?.at ? Date.parse(next.at) : null };
1294
+ },
1295
+ });
1296
+ ```
1297
+
1298
+ - **Re-arming.** SQL triggers on the `watch`ed tables (tenant tables of the
1299
+ organization object, by export or SQL name) mark the schedule in the write's
1300
+ own transaction, so every write path counts — actions, jobs, bulk
1301
+ statements. After each request, job or alarm the object re-arms marked
1302
+ schedules `debounceSeconds` later (default 5, 0–3600), unless one is already
1303
+ due sooner or is backing off after a failure: a re-arm never postpones a run
1304
+ or resets a retry budget. The schedule's own writes never mark it (no
1305
+ self-re-arm loop). A request (its deferred work included), command or job
1306
+ that overlapped the run while a watched table was written (an unmuted
1307
+ per-schedule write counter) brings the next run forward to the debounce —
1308
+ at most one extra run per overlapping operation, since the counter also
1309
+ sees the run's own writes. A watched name that resolves to no table is
1310
+ skipped and logged (`tenant.schedule.table_unresolved`).
1311
+ - **From the edge.** `armTenantSchedules(env, tenantId, types?)` re-arms an
1312
+ organization's schedules (all, or the given job types) for a change its
1313
+ writes cannot see — an edge-side row, a deploy. A deploy that adds or changes
1314
+ a schedule marks it on each organization's next wake; operators can arm
1315
+ everyone at once with `POST /tenants/schedules/arm-all` (a manual, bounded
1316
+ one-off — never a cron) or one organization with
1317
+ `POST /tenants/:id/schedules/arm`. An explicit arm also cuts a dead-letter
1318
+ cooldown short (after deploying a fix); a write does not.
1319
+ - **At least once.** A run is an alarm occurrence: `runId` is stable for it, a
1320
+ throw retries it with backoff and a dead letter is recorded as above; the
1321
+ schedule itself never stops. Completion is recorded only after the next
1322
+ occurrence is written; an occurrence found already complete is evaluated
1323
+ again after the debounce, never dropped.
1324
+ - **Restores.** A point-in-time restore rewinds the schedule rows, the marks
1325
+ and the data together, so they stay consistent; the platform alarm is re-armed
1326
+ from the rows when the object serves again, and every schedule is marked for
1327
+ one fresh evaluation. Work due between the restore target and the restore
1328
+ may have run on the abandoned timeline and runs again: `schedule.restoredAt`
1329
+ (the last restore, ms, or null) on the execute context lets a handler skip
1330
+ external side effects for it. A dump restore keeps the alarm rows (they are
1331
+ not tenant tables) and marks every schedule the same way.
1332
+ - **Placement.** Schedules run in organization objects only. `schedule:`
1333
+ needs `tenant: true`, is refused on a result job, on a `qb:`-prefixed type,
1334
+ and in shared tenancy (`TENANCY_SCHEDULE`); it must be `true` or a literal
1335
+ object.
1336
+
1337
+ ### Platform queues
1338
+
1339
+ Tenant code has no queue bindings (`TENANCY_ENV_UNAVAILABLE`). To hand work to
1340
+ the edge — email, push, webhooks — it sends a message to one of the edge
1341
+ Worker's queue bindings through the object's outbox:
1342
+
1343
+ {/* doc-compile: skip — action body fragment */}
1344
+ ```ts
1345
+ import { defineAction, tenantRuntime } from "../.quickback/define-action";
1346
+ // …
1347
+ tenantRuntime(env).enqueue("COMMS_QUEUE", { type: "mail.send", guestId: row.id });
1348
+ ```
1349
+
1350
+ - **Same write.** The call writes an outbox row with the request's writes. The
1351
+ edge drains the outbox after the response and calls
1352
+ `env.COMMS_QUEUE.send({ ...message, tenantId, dedupeKey })`. The row is
1353
+ written at the call: it is not dropped if `execute` later throws or returns
1354
+ a dry run. To send only after a successful `execute`, use
1355
+ `effects.enqueue(binding, message)`.
1356
+ - **`tenantId` comes from the object.** The edge stamps the tenant from the
1357
+ object's name. A message that sets `tenantId` or `dedupeKey` itself throws
1358
+ (`TENANT_QUEUE_MESSAGE`); nothing is written.
1359
+ - **At least once.** A failed send keeps the entry queued and it is retried
1360
+ with backoff ([outbox delivery](#outbox-delivery)), so a consumer can see a
1361
+ message twice. `dedupeKey` (a UUID fixed when the row is written) is the same
1362
+ on every delivery: use it as the consumer's idempotency key.
1363
+ - **Receipts.** `enqueue(binding, message, { ref })` records `ref` (1–200
1364
+ characters) on the row's [delivery receipt](#delivery-receipts). Point it at
1365
+ your own per-send row, such as a `comms_log` id, instead of copying that row
1366
+ into the receipt. The receipt also carries the `dedupeKey`, so a consumer that
1367
+ stores `dedupeKey` on its row links the two the other way.
1368
+ - **Size.** A message over 120 KiB of JSON, or one that is not
1369
+ JSON-serializable, throws at the call (`TENANT_QUEUE_MESSAGE_TOO_LARGE`,
1370
+ `TENANT_QUEUE_MESSAGE`). A row the edge can never send (a binding missing
1371
+ from the edge Worker, a message the queue refuses) is dead-lettered so it
1372
+ does not block the outbox.
1373
+ - **Declared bindings only.** The binding must be one of the edge Worker's
1374
+ queues (the primary queue and `additionalQueues`). The build refuses any
1375
+ other name, or a name it cannot read (not a string literal), in tenant
1376
+ actions, tenant jobs, JS trigger handlers and the helpers they import
1377
+ (`TENANCY_QUEUE_BINDING`); at runtime the object refuses it
1378
+ (`TENANT_QUEUE_UNKNOWN`), and the drain dead-letters a row naming an
1379
+ unknown binding.
1380
+ - A tenant job uses `tenant.enqueue(binding, message)`, the same call.
1381
+ `effects.enqueue(binding, message)` and table-level transition
1382
+ `onEnter.enqueue` steps in tenant features route through it too, after
1383
+ `execute` succeeds and before the response. A refusal there
1384
+ (`TENANT_QUEUE_*`) fails the response.
1385
+
1386
+ The consumer is a platform queue handler: it runs on the edge, with the
1387
+ platform D1. If it needs the tenant's data, it calls a
1388
+ [result job](#result-jobs) with `message.tenantId`. That value is
1389
+ authoritative only for messages from a tenant outbox (the edge stamped it). A
1390
+ queue that edge code also produces to carries whatever that producer wrote:
1391
+ edge producers must set `tenantId` from the caller's `ctx`
1392
+ (`ctx.activeOrgId`), never from request input. A restore discards queued `queue` entries with the other outbox
1393
+ entries that are neither audit rows nor scope revocations.
1394
+
1395
+ ### Result jobs
1396
+
1397
+ Edge code sometimes needs an answer from a tenant's database: a public page
1398
+ showing an organization's data, or a platform action that reads tenant state.
1399
+ Edge code can't query tenant tables (`TENANCY_ADMISSION_DEPENDENCY`), and
1400
+ cross-tenant `unsafe` or root-path actions can't move into a tenant feature
1401
+ (`TENANCY_UNSAFE_ACTION`, `TENANCY_ROOT_ACTION`). They stay on the edge, in a
1402
+ platform feature, and call a **result job**: a tenant job declared with
1403
+ `result: true` and a `resultSchema`.
1404
+
1405
+ {/* doc-compile: skip — needs a reminders feature */}
1406
+ ```ts title="quickback/services/queues/reminderCount.ts"
1407
+ import { z } from "zod";
1408
+ import { eq } from "drizzle-orm";
1409
+ import { defineQueue } from "@quickback/compiler";
1410
+ import { reminders } from "../../features/reminders/schema";
1411
+
1412
+ export default defineQueue<{ type: "reminder.count"; tenantId: string; ownerId: string }>({
1413
+ name: "reminderCount",
1414
+ messageType: "reminder.count",
1415
+ tenant: true,
1416
+ result: true,
1417
+ resultSchema: z.object({ open: z.number().int() }),
1418
+ execute: async ({ message, db }) => {
1419
+ const rows = await db.select().from(reminders).where(eq(reminders.ownerId, message.ownerId));
1420
+ return { success: true, result: { open: rows.filter((r) => !r.sentAt).length } };
1421
+ },
1422
+ });
1423
+ ```
1424
+
1425
+ {/* doc-compile: skip — action body fragment */}
1426
+ ```ts
1427
+ import { callTenantJob, resolveTenant } from "../../../lib/tenants";
1428
+
1429
+ const tenantId = await resolveTenant(env, "inviteCode", input.code); // or ctx.activeOrgId
1430
+ if (!tenantId) throw new ActionError("Unknown code", "NOT_FOUND", 404);
1431
+ // The edge action is the only authorization gate: check here that this caller may ask this question.
1432
+ const runId = "reminder-count:" + crypto.randomUUID(); // built on the server, never from the request
1433
+ const res = await callTenantJob<{ open: number }>(env, tenantId, { type: "reminder.count", ownerId: input.ownerId }, runId);
1434
+ if (res.status === "unavailable") throw new ActionError("Try again shortly", res.code, 503);
1435
+ if (res.status === "failed") throw new ActionError("Lookup failed", "LOOKUP_FAILED", 422); // res.error stays server-side
1436
+ return res.result;
1437
+ ```
1438
+
1439
+ `callTenantJob(env, tenantId, message, runId)` returns
1440
+ `{ status: 'ok', result } | { status: 'failed', error } | { status: 'unavailable', code }`:
1441
+
1442
+ | Result | When |
1443
+ |---|---|
1444
+ | `ok` | The handler returned `{ success: true, result }`. The object validated `result` against `resultSchema` and checked that it serializes to at most **256 KiB**, then recorded it with the run marker in one transaction. |
1445
+ | `failed` | The handler returned `{ success: false, error }` (that `error`, capped at 200 characters), threw (`TENANT_JOB_FAILED`; the error text is never returned, only logged as the job type and code), called `retry()`, or its result failed the schema (`TENANT_JOB_RESULT_INVALID`) or the size cap (`TENANT_JOB_RESULT_TOO_LARGE`). Also `TENANT_JOB_RUN_CONFLICT`, below. Nothing is recorded, so the same `runId` runs again. Writes the handler made are kept: key them by `runId`. |
1446
+ | `unavailable` | The registry gate shared with [tenant commands](#tenant-commands) (`TENANT_NOT_PROVISIONED`, `TENANT_PURGED`, `TENANT_JURISDICTION_MISMATCH`, `TENANT_UNAVAILABLE`), an archived, purged or unmigrated object (`TENANT_ARCHIVED`, `TENANT_PURGED`, `TENANT_MIGRATION_FAILED`), a pending restore, an RPC failure (`TENANT_OVERLOADED`, …), version skew, or a malformed reply (`TENANT_JOB_REPLY_INVALID`). The job may or may not have run. |
1447
+
1448
+ `resultSchema` must be `z.object({ … })`, which strips unknown keys, or a
1449
+ strict object (`z.strictObject`, `.strict()`), which refuses them, written
1450
+ inline or as a top-level const. A passthrough, loose or catchall schema fails
1451
+ the build (`TENANCY_JOB_RESULT_SCHEMA`).
1452
+
1453
+ A repeated `runId` with the same message replays the recorded result without
1454
+ running the handler again, for seven days; after that the `runId` runs again.
1455
+ `resultTtlSeconds` (a number literal, 60 to 604800) shortens that for one job:
1456
+ a result older than that is gone (with its run marker) the next time its
1457
+ `runId` is called, and expired results are deleted whenever a result is
1458
+ recorded or the object's alarm runs. Use it for read-only pulls, such as an
1459
+ export that reads pages of the tenant's data, whose results should not sit in
1460
+ the tenant's SQLite for a week. The 60-second floor keeps `callTenantJob`'s
1461
+ own resend after an object reset (same `runId`) a replay rather than a second
1462
+ run. Anything else (a non-literal, out of range, or without `result: true`)
1463
+ fails the build (`TENANCY_JOB_RESULT_TTL`).
1464
+ The result is bound to a hash of the canonical message (sorted keys): the same
1465
+ `runId` with any other field is `failed` / `TENANT_JOB_RUN_CONFLICT`, never
1466
+ the earlier caller's result. Calls have their own run-id space (`call:` on the
1467
+ object; `runJob` and `deliverTenantJob` refuse run ids with that prefix), so a
1468
+ call never replays a queue, alarm or outbox run. Concurrent calls with one
1469
+ `runId` and one message share one execution. Build the `runId` on the server
1470
+ (a fresh id, or one from your own idempotency record), never from request
1471
+ input. The call is retried once after an object reset or a retryable RPC
1472
+ error, and drains the object's outbox after an `ok`.
1473
+
1474
+ **Authorization.** A result job runs with system rights in the tenant's object:
1475
+ no caller, no firewall, no access rules. The edge code that calls it is the
1476
+ only authorization gate, so check there that this caller may ask this
1477
+ question. The build requires the tenant argument to be visibly server-verified
1478
+ (`TENANCY_JOB_CALL_TENANT_SOURCE`): `ctx.activeOrgId` / `ctx.tenantId`, a
1479
+ `resolveTenant(...)` or `resolvePrincipalTenant(...)` result (directly or
1480
+ through a `const`), or a `forEachTenant` callback's tenant. If it is verified
1481
+ another way, such as a signed webhook naming the organization, put
1482
+ `// quickback-allow-tenant-source: <reason>` on the line above the call.
1483
+
1484
+ The object refuses, before the job runs, a message that is not a result job,
1485
+ a message for another tenant, a partition or control object, or a missing
1486
+ `runId` (`TENANT_JOB_INVALID`). It sets `tenantId` from the object's name. The
1487
+ edge helper throws on the same caller bugs. Pass only a server-verified
1488
+ organization id: a session's organization, or one resolved through
1489
+ [`tenancy.lookups`](#lookup-indexes).
1490
+
1491
+ A result job is only ever called. A `{ type: '<result job>' }` message literal
1492
+ anywhere but `callTenantJob`'s message argument fails the build
1493
+ (`TENANCY_JOB_RESULT_PRODUCER`), and at runtime `runJob`, `schedule`, `send`,
1494
+ `deliverTenantJob` and `scheduleTenantJob` refuse it (`TENANT_JOB_CALL_ONLY`).
1495
+ One that reaches a queue anyway is retried into the dead-letter queue. An
1496
+ outbox entry or a scheduled alarm for a job that has since become a result job
1497
+ is dropped as a dead letter (logged), so it never blocks the outbox or the
1498
+ alarm.
1499
+ `resultSchema` is required with `result: true`, `result` must be the literal
1500
+ `true`, and the handler must be a tenant job (`TENANCY_JOB_RESULT_SCHEMA`).
1501
+ Result jobs need `isolation: 'durable-object'`.
1502
+
1503
+ Realtime broadcasts from tenant tables (`realtime: { enabled: true }`) are
1504
+ recorded in the object's outbox with the write and replayed by the edge through
1505
+ the Broadcaster as the response returns ([outbox delivery](#outbox-delivery)).
1506
+ `createRealtime` in tenant code has the
1507
+ edge's shape, `defineRealtime` namespaces included: `realtime.<namespace>.<event>(…)`
1508
+ is queued as the same `broadcast('<namespace>:<event>', …)` the edge sends.
1509
+
1510
+ ### Outbox delivery
1511
+
1512
+ Everything a tenant object hands the edge goes through its outbox, a table in
1513
+ the object's SQLite written in the same transaction as the writes that caused
1514
+ it:
1515
+ - realtime frames;
1516
+ - `audit_events` rows;
1517
+ - lookup-index changes;
1518
+ - jobs for other objects;
1519
+ - platform queue messages;
1520
+ - scope revocations ([`revocationCheck: 'kv'`](#scope-revocation)).
1521
+
1522
+ The edge delivers each entry at least once, even if the request's `waitUntil`
1523
+ is cut off.
1524
+
1525
+ - **Claimed, never shared.** An entry is claimed before anything applies it:
1526
+ the object reads it and leases it to that claimer for 30 seconds in one
1527
+ synchronous turn. Two drains, two responses, or a response and a sweep never
1528
+ hold the same entry, so a frame is not broadcast twice.
1529
+ - **In the response.** A `handle()` response carries what it claimed: at most
1530
+ 32 entries, or 32 KiB of them, in the `x-quickback-tenant-outbox-claim`
1531
+ header, which the edge strips. The edge does not call the object again to
1532
+ fetch them. Entries over those caps stay claimable. The response says how
1533
+ many remain, and the edge claims them with `claimOutbox`.
1534
+ - **Realtime first.** The edge publishes the claimed realtime frames before
1535
+ the response leaves it, in seq order within a claim, one Broadcaster call at
1536
+ a time. No D1 read or write happens before them. The registry report and
1537
+ the D1 bookkeeping run beside the frames, never in front of them.
1538
+ - **Revocations beside realtime.** `revoke` entries are stamped into the
1539
+ edge's revocation KV as soon as a claim arrives, beside the realtime frames
1540
+ and never behind the D1 bookkeeping or the restore fence. Like the frames,
1541
+ the write starts before the response leaves the edge, and for a kind the
1542
+ tenant admits (a tenant-backed scope kind) the response does not wait for
1543
+ it. Every lane that admits such a claim (the namespace gate, edge actions,
1544
+ tickets, refresh and authorize) re-proves it against the tenant's own rows,
1545
+ which the same write changed, so the removed subject is refused on its very
1546
+ next request, whatever KV says. A revocation of any other kind (a manual
1547
+ `revokeScopeTokens` on a platform kind, whose claims are proven against the
1548
+ platform database) has no such check, so a response carrying one returns
1549
+ once the KV is written (waiting at most 2 seconds). That makes the
1550
+ revocation visible at once in the location that wrote it; elsewhere it
1551
+ arrives within KV's propagation time (up to about a minute). Each
1552
+ (subject, kind, instance) is written once per claim. A KV failure or a
1553
+ missing `KV` binding retries the entry; a revocation is never dropped. An
1554
+ entry whose request ended before it was written is claimed again by the
1555
+ next response or drain for that object once its 30-second lease lapses.
1556
+ - **Ordered lane.** Lookup and registry entries go to D1 in one batch, guarded
1557
+ by `tenant_registry.outbox_seq` and the restore fence
1558
+ (`outbox_generation`, `restore_session`), which the batch reads back.
1559
+ Only one claim holding them is in flight at a time, and a later one is never
1560
+ claimed before an earlier one, so the index sees them in order. Audit rows,
1561
+ jobs and queue messages are applied only when that fence holds; otherwise
1562
+ they are released for the reconciling drain.
1563
+ - **Settled, with a receipt.** The edge reports each entry back as one of:
1564
+ - `delivered`: the row is deleted.
1565
+ - `retry`: the row is kept and released with backoff (1 s doubling to
1566
+ 60 s). A realtime frame is retried three times, then recorded failed.
1567
+ - `failed`: the row is dead-lettered (`__qb_outbox_dead`, counted in
1568
+ `tenant_registry.outbox_dead_letters`), or dropped for realtime.
1569
+
1570
+ Settlements ride on the edge's next request to that object from the same
1571
+ isolate. Only if a settlement is still waiting a second later does one
1572
+ `settleOutbox` call carry everything pending, in calls of at most 64.
1573
+ Failures, fence releases, and a claim that holds later lookup or registry
1574
+ rows back settle at once. Any other claim holding lookup or registry rows
1575
+ waits only 50 ms for a request to carry it. Until it settles, the lane is
1576
+ blocked, and an isolate that dies inside that window leaves the lane blocked
1577
+ until the lease expires and the next response or sweep claims the rows. A settlement that never arrives changes nothing:
1578
+ its entries are claimed again after the lease, so delivery stays at least
1579
+ once. That covers an isolate that died, an object that refused the
1580
+ settlement, or a request answered `503 TENANT_RPC_VERSION_MISMATCH` before
1581
+ the settlement it carried was read.
1582
+ - **First request.** On an object's first request the report write (which
1583
+ registers it in `tenant_registry`) finishes before the claim's lookups,
1584
+ audit rows, jobs and queue sends are applied. Realtime does not wait for it.
1585
+ - **Oversized rows.** A row too large for the inline header is claimed by
1586
+ `claimOutbox`, which always hands over the oldest claimable row, whatever its
1587
+ size.
1588
+ - **Operator drains.** `sync` and `backup` drain an active object normally.
1589
+ For an archived object (and during purge, restore and unarchive) they also
1590
+ take entries another claim holds, and a failed realtime replay is not
1591
+ retried. An archived object serves no requests, so nothing else would
1592
+ deliver them.
1593
+ - **Chained jobs.** A job delivered to another object of the organization
1594
+ drains that object's outbox too (up to 4 levels deep), after the claim that
1595
+ carried the job is settled.
1596
+ - **When a claimer dies.** Its entries stay leased until the lease expires,
1597
+ then the next response or sweep claims them again. A realtime frame keeps
1598
+ the `publishId` written with the row, so the Broadcaster drops a repeat it
1599
+ remembers, and the frame `id` (`evt_<publishId>`) lets clients drop the rest.
1600
+ Other kinds were already idempotent: audit rows by id, jobs by run id, queue
1601
+ messages by `dedupeKey`.
1602
+ - **Order.** Realtime frames are ordered within one claim. Across concurrent
1603
+ requests they are not, as before. Realtime no longer waits for the jobs and
1604
+ queue sends of the same claim.
1605
+
1606
+ #### Delivery receipts
1607
+
1608
+ Each settled entry leaves a row in the object's `__qb_outbox_receipts` table:
1609
+ - `generation` and `seq`;
1610
+ - `kind`;
1611
+ - `method`: the realtime method or event, or the job or queue message type;
1612
+ - `target`: the Broadcaster shard, job target, queue binding, audit row id or
1613
+ lookup name;
1614
+ - `ref`;
1615
+ - `createdAt` and `sentAt` (ms);
1616
+ - `attempts`;
1617
+ - `outcome` (`delivered`, `retrying` or `failed`) and `reason`;
1618
+ - `detail`: `{ publishId, matched, duplicate }` for realtime, where `matched`
1619
+ is the number of sockets the Broadcaster sent to; `{ dedupeKey }` for queue
1620
+ messages; `{ runId }` for jobs.
1621
+
1622
+ A receipt moves to `delivered` and stays there. Receipts are written in the
1623
+ same object turn as the settlement, so they cost no extra request.
1624
+
1625
+ - **Retention.** Receipts older than `tenancy.outbox.receipts.retainDays`
1626
+ (default 7), and the oldest beyond `maxRows` (default 50 000), are pruned on
1627
+ the object's alarm, on the first settlement after each wake, and after every
1628
+ 256 settled entries.
1629
+ - **Backups and restore.** Receipts are not tenant data. Dumps skip them, and
1630
+ a dump restore keeps them, because restoring data does not undo what was
1631
+ already sent. A point-in-time restore rewinds the whole object, so it rewinds
1632
+ receipts and outbox rows (with their leases) to the bookmark as well. The
1633
+ reconciling sync then moves to a new outbox generation, drops the rewound
1634
+ non-audit rows and releases every lease. Settlements still in flight for the
1635
+ old generation write their receipts but touch no row. Purge erases receipts
1636
+ with the object.
1637
+ - **Reading them.** `GET <api>/tenants/:id/outbox-receipts?since=<ms or ISO>&limit=<1-1000>&outcome=delivered|retrying|failed`
1638
+ (sysadmin, oldest first). It returns `{ receipts, next }`; pass `next` as
1639
+ `since` for the next page. In code, call
1640
+ `listTenantOutboxReceipts(env, name, { since, limit, outcome })` from
1641
+ `src/lib/tenants.ts`.
1642
+ - **Push and email.** These already keep a per-send row in your own tenant
1643
+ table (for example `comms_log`). Pass that row's id as `ref` when enqueueing
1644
+ instead of duplicating it.
1645
+
1646
+ ### Vars in tenant code
1647
+
1648
+ The tenant Worker has no bindings of the edge's, vars included, so tenant code
1649
+ that reads `env.<NAME>` fails the build (`TENANCY_ENV_UNAVAILABLE`). List the
1650
+ plain vars it needs in `tenancy.vars`:
1651
+
1652
+ ```ts
1653
+ tenancy: {
1654
+ isolation: "durable-object",
1655
+ vars: ["ATTENDEE_APP_URL"],
1656
+ },
1657
+ environments: {
1658
+ dev: { /* … */ worker: { vars: { ATTENDEE_APP_URL: "https://app-dev.example.com" }, /* … */ } },
1659
+ },
1660
+ ```
1661
+
1662
+ Each target's tenant Worker gets the value its own edge has (`[env.<name>.vars]`,
1663
+ or the top-level `[vars]` without environments), so tenant code reads
1664
+ `env.ATTENDEE_APP_URL` like edge code does; a target that does not set it gets
1665
+ none. Only plain vars qualify: a declared secret (`bindings.secrets`, a target's
1666
+ `requiredSecrets`, a `secrets.required` name of the edge) or a name that reads
1667
+ like one (`*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*_PASS`/`_PW`/`_PWD`,
1668
+ `*PRIVATE*`, `*CREDENTIAL*`, `*APIKEY*`, `*SALT*`, `*_SIGNING*`, `*_HMAC*`,
1669
+ `*PEPPER*`, `*BASIC_AUTH*`, `*_DSN`, database / Redis / Mongo `*_URL*` and
1670
+ `*_URI*`, `*CONNECTION_STRING*`, `*_PEM`, and `*_KEY(S)` / `*_KEK(S)` other
1671
+ than `*_PUBLIC_KEY(S)`, `*_SITE_KEY(S)` and `*_PUBLISHABLE_KEY(S)`) fails
1672
+ the build (`TENANCY_VARS_SECRET`), as does a
1673
+ name no target defines as a string var (`TENANCY_VARS_UNDECLARED`). Every other
1674
+ `env.*` read in tenant code still fails.
1675
+
1676
+ ### Edge-only modules in tenant code
1677
+
1678
+ `lib/realtime` (needs the Broadcaster), `lib/security-audit` (needs the audit
1679
+ database) and `lib/auth` (Better Auth) do not run in the tenant Worker. Loading
1680
+ one there would drop its side effect silently, so the compiler guarantees:
1681
+
1682
+ - **Rewritten.** In tenant feature files and tenant queue handlers, a value
1683
+ import of `lib/realtime` or `lib/security-audit` is pointed at the tenant
1684
+ version, which records the event in the object's outbox. This covers
1685
+ `import`/`export … from` in either quote style, `import "…"`, and
1686
+ `import("…")`/`require("…")` with a literal path (quotes or a backtick with
1687
+ no `${}`). The path is resolved against the importing file, so only paths
1688
+ that land on the project's `lib/` change. `import { createAuth } from
1689
+ "…/lib/auth"`, optionally aliased and with `type` names alongside, becomes a
1690
+ stand-in that throws: read the caller from `ctx` instead.
1691
+ - **Refused.** The build then walks every module the tenant Worker loads from
1692
+ `src/tenant/index.ts` (again after provider build hooks, so a file a hook
1693
+ adds or rewrites is checked too) and fails (`TENANCY_EDGE_IMPORT_IN_TENANT`, with the
1694
+ import chain) on any value reference to one of those modules that remains:
1695
+ a shared `quickback/lib` helper or a platform feature that imports
1696
+ `./realtime`, any other import from `lib/auth`, or a string that resolves
1697
+ to one of them (a relative path, or one starting `@/`, `~/` or `src/` — so
1698
+ `"src/lib/auth"` itself is refused). It also refuses every `import()` or
1699
+ `require()` whose argument is not a plain string literal (`+`, a template
1700
+ with `${}`, a variable, `.join()`): the compiler cannot check it, and the
1701
+ bundler includes every file such a pattern could match. Shared modules are not rewritten
1702
+ because the edge Worker uses them too: import `lib/realtime` from the tenant
1703
+ feature itself, or keep the helper free of it.
1704
+ - **Allowed.** `import type`, `type` specifiers, `typeof import("…")`, comments
1705
+ and ordinary strings.
1706
+
1707
+ ### Helpers run where their caller runs
1708
+
1709
+ A helper a tenant action, tenant job or JS trigger handler imports runs inside
1710
+ the tenant object too. After all files are generated, the compiler walks each
1711
+ of them through its runtime imports, resolving relative imports and
1712
+ `tsconfig.json` `paths` aliases the way the edge-bundle walk does. Every
1713
+ authored module it reaches, such as a feature `lib/` file, another feature's
1714
+ file or a `quickback/lib` helper, gets the checks a tenant action gets:
1715
+
1716
+ - edge-only `ctx` members and `env` bindings (`TENANCY_CTX_UNAVAILABLE`,
1717
+ `TENANCY_ENV_UNAVAILABLE`);
1718
+ - async `transaction()` callbacks (`TENANCY_ASYNC_TRANSACTION`);
1719
+ - tables of another object (`TENANCY_CROSS_PARTITION`);
1720
+ - inserts that choose the id of a scope instance or proving table
1721
+ (`TENANCY_ADMISSION_ID_STRATEGY`).
1722
+
1723
+ A tenant job's own body (its top-level constants and `execute`) gets the same
1724
+ checks. The checks are per module, not per function: a helper file is scanned
1725
+ whole once anything imports it, including exports the caller never uses.
1726
+
1727
+ The error names the helper and the entry point that reached it. Compiler-
1728
+ generated modules are not expanded, and package imports are allowed. A relative
1729
+ or alias import that names no file in the build, or a computed `import()` /
1730
+ `require()`, fails with `TENANCY_HELPER_UNRESOLVED`: the compiler can't check
1731
+ code it can't find. A helper nothing in the tenant Worker imports is not checked.
1732
+
1733
+ JS `handler:` triggers on tenant tables run in the object as well. Each
1734
+ handler's source gets the same checks as an action body, and its imports are
1735
+ walked like a helper's. A handler receives the `env` a tenant action gets (a
1736
+ copy of the tenant Worker's bindings without the backup bucket, which holds
1737
+ every organization's dumps; `tenancy.backup.bucket` may not double as any
1738
+ app, provider or queue binding), so
1739
+ whatever it passes `env` to records into the object's outbox in the same way:
1740
+ `createRealtime(env)` broadcasts, `tenantRuntime(env).enqueue(…)` queue
1741
+ messages and the tenant `revokeScopeTokens(env, …)`. The tenant
1742
+ `createRealtime` logs `tenant.realtime.no_outbox` (an error) when it is given
1743
+ an `env` without the outbox, instead of dropping the call silently. A handler whose source can't be extracted as one arrow
1744
+ function or function expression fails with `TENANCY_TRIGGER_UNVERIFIABLE`.
1745
+
1746
+ ## Scope revocation
1747
+
1748
+ With `auth.jwt.revocationCheck: 'kv'`, changing a scope-conferring row revokes
1749
+ the carried scope claims that row backed (revoke-on-touch): the subject's
1750
+ `qbrev:scope:<subject>:<kind>:<instance>` keys are stamped in the edge's `KV`
1751
+ namespace. The tenant Worker has no `KV`, so for a tenant table the object
1752
+ records the revocation in its outbox and the edge stamps it:
1753
+
1754
+ - **In the write's transaction.** Every scope-conferring tenant table (the
1755
+ `from` table of a relationship a scope role is granted `via`) carries SQL
1756
+ triggers that write a `revoke` outbox entry on every `DELETE` and on every
1757
+ `UPDATE` that changes a column the row confers through (soft deletes
1758
+ included), naming the row's id and subject column and its resource
1759
+ (instance) column. Those columns are the subject and resource columns, each
1760
+ relationship's `where:` columns, every scope role's `subKeys`, every field
1761
+ the table's firewall names (its soft-delete column included), the tenant
1762
+ column and the primary key, so a backfill or data migration of other
1763
+ columns revokes nothing. When the compiler cannot resolve one of them, the
1764
+ trigger fires on every `UPDATE`. An update that moves the row to another subject or instance also
1765
+ revokes the new pair. Being SQL triggers, they fire for every write path in
1766
+ the object: CRUD routes, actions, `unsafeDb`, jobs, trigger handlers,
1767
+ foreign-key cascades and compiler commands. A write that rolls back leaves
1768
+ no revocation. `INSERT OR REPLACE` deletes a conflicting row without firing
1769
+ the `DELETE` trigger (SQLite's `recursive_triggers` stays off, so authored
1770
+ SQL triggers keep their semantics): the build refuses `INSERT OR REPLACE` /
1771
+ `REPLACE INTO` on a conferring table in tenant actions and trigger bodies
1772
+ (`TENANCY_REVOCATION_REPLACE`). Change a conferring row with an `UPDATE`
1773
+ (or `onConflictDoUpdate`).
1774
+ - **Stamped by the edge**, at least once, beside the realtime frames (see
1775
+ [Outbox delivery](#outbox-delivery)), at the time the edge applies the entry,
1776
+ like every edge revocation: a later stamp only revokes more (a token proven
1777
+ between the write and the stamp re-proves), and no stale read can lower it.
1778
+ The entry keeps its write time for the receipt. The edge accepts a `revoke`
1779
+ entry only for a declared `authz.scopes` kind; one whose instance the
1780
+ platform lookup index places in another organization is logged
1781
+ (`tenant.revoke.foreign_instance`) and still applied, since a wrong
1782
+ revocation only forces a re-prove.
1783
+ - **Restores and purges.** A dump restore drops the tables, and a purge erases
1784
+ the database, without firing a trigger; a point-in-time restore rewinds the
1785
+ outbox with the data. So a dump restore first queues a revocation for every
1786
+ conferring row it replaces, in the load's transaction. A point-in-time
1787
+ restore hands the current conferring rows and any queued revocations to the
1788
+ control object before scheduling the rewind. Every reconcile
1789
+ (`POST /tenants/:id/sync`, abandon) and every cancel queues them again, and
1790
+ only a reconcile drops them once its requeue committed (an orphaned stash is
1791
+ pruned after a week). A purge queues them once per archive, then drains them
1792
+ in rounds, at most 300 rows per request (each row costs up to two KV writes,
1793
+ and a Worker invocation gets about 1000 KV operations). While any remain it
1794
+ answers `409 TENANT_PURGE_DRAINING` with `details: { remaining, more }` and
1795
+ `Retry-After`: retry the purge until it completes; nothing is queued twice. An edge older
1796
+ than version 12 cannot purge while revocations are queued. Rows that exist
1797
+ again after a restore simply re-prove.
1798
+ - **Your own revocations.** In tenant code, `revokeScopeTokens(env, subject, kind, instanceId)`
1799
+ (an import of `lib/jwt-revocation` in a tenant feature is re-pointed at the
1800
+ tenant version) records a `revoke` entry with your write. It takes the `env`
1801
+ your action, job or trigger handler received, never `env.KV`, and throws
1802
+ `TENANT_REVOCATION_UNAVAILABLE` without the outbox. The other exports of
1803
+ `lib/jwt-revocation` (`revokeUserTokens`, `revokeMemberTokens`,
1804
+ `revokeSessionTokens`, `checkTokenRevocation`) are edge-only: in a tenant
1805
+ feature a call fails the build, its parameter type naming the reason.
1806
+ - **Admission.** A revoked claim stops riding on tokens; admission itself
1807
+ re-reads the row. [Tenant scope admission](#tenant-backed-scope-kinds)
1808
+ requires the proving row's conditions (`where:`) and excludes soft-deleted
1809
+ rows through the table's firewall (`deleted_at IS NULL`).
1810
+
1811
+ ## Lookup indexes
1812
+
1813
+ Some lookups start from a value, not an organization: an invite code, a public
1814
+ slug, an SES message id, a phone number. Declare them in `tenancy.lookups`:
1815
+
1816
+ {/* doc-compile: skip — fragment of quickback.config.ts */}
1817
+ ```ts
1818
+ lookups: {
1819
+ inviteCode: { table: "invites", column: "code", hash: true },
1820
+ event: { table: "events", column: "id" },
1821
+ },
1822
+ ```
1823
+
1824
+ SQL triggers in every tenant object record each insert, update and delete of
1825
+ the column (soft-deleted rows count as deleted) in the object's outbox. The
1826
+ edge applies them to the platform `tenant_lookups` table after the response, in
1827
+ order (`tenant_registry.outbox_seq` drops a stale batch). Read it on the edge:
1828
+
1829
+ {/* doc-compile: skip — generated-project code */}
1830
+ ```ts
1831
+ import { resolveTenant, resolveTenants } from "../lib/tenants";
1832
+
1833
+ const tenantId = await resolveTenant(env, "inviteCode", code); // null, or throws if several
1834
+ const phoneTenants = await resolveTenants(env, "phone", phone);
1835
+ ```
1836
+
1837
+ A lookup named after a scope kind resolves tokens: an instance-bound token
1838
+ (`ctx.oauth.boundTo`) or a scope-only principal (`ctx.scope.<kind>.id`) reaches
1839
+ the organization whose rows hold that id. Without a matching lookup those
1840
+ principals get `400 TENANT_REQUIRED`. A token for a
1841
+ [tenant-backed kind](#tenant-backed-scope-kinds) is the exception:
1842
+ it routes to the tenant it pins, and the lookup is used only to issue it.
1843
+
1844
+ The index converges, it is not transactional with the write: it lags until
1845
+ the edge drains the object's outbox (after that object's next response, or
1846
+ `syncTenants(env)`). Adding a lookup re-sends every current key on each
1847
+ object's next wake.
1848
+
1849
+ ### Hashed lookups
1850
+
1851
+ Every organization's lookup rows share one D1. A lookup whose values are
1852
+ credentials (invite tokens, share-link tokens, sign-in codes) should not sit
1853
+ there in plaintext: set `hash: true`. The row's key is then `h1:` followed by
1854
+ `HMAC-SHA256(TENANT_LOOKUP_KEY, "<name>\0<value>")` as 64 lowercase hex. The
1855
+ `h1:` marker tells a hash from a value that is itself hex, so a row written
1856
+ before hashing is always recognisable. The lookup name separates domains, so
1857
+ the same value in two lookups gets two unrelated keys. A lookup column whose name reads like a credential (`token`,
1858
+ `code`, `secret`, `key`, `password`) and is not hashed draws a
1859
+ `TENANCY_LOOKUP_PLAINTEXT` compile warning. Ids and slugs are fine in plaintext.
1860
+
1861
+ - **The secret.** `TENANT_LOOKUP_KEY` is required on the edge Worker (it joins
1862
+ the generated secret inventory and the boot guard): one or more 64-hex keys
1863
+ (`openssl rand -hex 32`), comma-separated, primary first. The tenant Worker
1864
+ never holds it. Its outbox carries the value to the edge, which hashes before
1865
+ anything reaches D1. A missing or malformed key refuses: the outbox entries
1866
+ retry, and resolution fails, so nothing is ever written in plaintext.
1867
+ - **Unchanged API.** `resolveTenant(env, name, value)` takes the value and
1868
+ hashes it. Receipts record the lookup name only. A dead-lettered lookup row
1869
+ copied to the audit database at purge has its value withheld.
1870
+ - **Rotation.** Resolution tries every key and re-keys a row it finds under an
1871
+ older one; writes use the first. Rotate in two deploys, so no isolate still
1872
+ on the old list writes a row the others cannot clean up: (1) append the new
1873
+ key (`old,new`) and deploy; (2) promote it (`new,old`) and deploy; (3) run
1874
+ `POST /tenants/:id/rebuild-lookups` on every organization, which re-publishes
1875
+ each object's rows under the new key; (4) drop the old key.
1876
+ - **Turning it off.** Removing `hash: true` (or rolling the edge back past it)
1877
+ leaves the hashed rows unresolvable: rebuild every organization's lookups
1878
+ afterwards.
1879
+ - **Adopting `hash: true` on an existing lookup.** Rows written before it hold
1880
+ the value. Resolution also matches the plaintext row (never a value shaped
1881
+ like a stored hash) and re-keys it. Every outbox drain of an object (a request,
1882
+ a job call, an alarm's drain request, an operator call) and its wake report
1883
+ convert up to 100 of that object's plaintext rows in place first, once per
1884
+ object per isolate. For organizations that do not wake, run
1885
+ `POST /tenants/lookups/migrate` (or `syncTenants(env)`, which also converts
1886
+ up to 200 rows across objects) until it reports none remaining — manually,
1887
+ not on a cron. Any write
1888
+ of a key replaces its plaintext row. Set the secret first, then deploy the
1889
+ tenant Worker, then the edge.
1890
+
1891
+ ## Partitions
1892
+
1893
+ One object per organization puts a busy organization on one thread. Shard a
1894
+ high-volume, naturally partitioned feature by its unit of contention:
1895
+
1896
+ {/* doc-compile: skip — fragment of a feature() resource config */}
1897
+ ```ts
1898
+ placement: { partition: "conversation", key: "conversationId" },
1899
+ ```
1900
+
1901
+ Each `(organization, key)` gets its own object, named `<orgId>:<key>`, so the
1902
+ object name alone says which tenant it serves. The table stays
1903
+ organization-scoped (the firewall still applies) and every table in the feature
1904
+ uses the same key.
1905
+
1906
+ | Request | Result |
1907
+ |---|---|
1908
+ | Key from `?conversationId=`, the `x-quickback-partition-key` header, or the JSON body field | Forwarded to `<orgId>:<key>`; the query parameter is consumed |
1909
+ | No key | `400 PARTITION_KEY_REQUIRED` |
1910
+ | Two different keys in one request | `400 PARTITION_KEY_MISMATCH` |
1911
+ | A row whose key differs from its object's | Refused by a trigger in the object (`400 PARTITION_KEY_MISMATCH`) |
1912
+
1913
+ Partition objects carry the same schema and migrations as organization
1914
+ objects (their organization tables stay empty), take their own backups, and
1915
+ appear in `tenant_registry` with `partition_key`. One partition kind per
1916
+ project (`TENANCY_PARTITION_KINDS`).
1917
+
1918
+ No foreign key and no action crosses partitions: the build refuses
1919
+ `TENANCY_FK_CROSS_PARTITION` and `TENANCY_CROSS_PARTITION`. Store the other
1920
+ side's id without `.references()` (opt it out of the reference diagnostic with
1921
+ `references: { projectId: { references: false, reason } }`) and send the update
1922
+ through the outbox — delivered by the edge after the response, at least once,
1923
+ to a tenant job in the target object:
1924
+
1925
+ {/* doc-compile: skip — action body fragment */}
1926
+ ```ts
1927
+ const [row] = await db.insert(messages).values({ conversationId: input.conversationId, body: input.body }).returning();
1928
+ tenantRuntime(env).send("tenant", { type: "conversation.posted", conversationId: input.conversationId });
1929
+ ```
1930
+
1931
+ `send("tenant", …)` targets the organization object; `send({ key }, …)` a
1932
+ partition object of the same organization.
1933
+
1934
+ ## Deleting the namespace
1935
+
1936
+ A `deleted` tombstone for `QuickbackTenant` destroys every tenant database.
1937
+ The build refuses a `bindings.durableObjectMigrations` entry that deletes or
1938
+ renames the class (`TENANCY_NAMESPACE_DELETION`) unless
1939
+ `tenancy.allowNamespaceDeletion: true` is set **and** no table still lives in
1940
+ a tenant object. Then the tenant Worker's exports carry
1941
+ `{ "state": "deleted" }` and the edge no longer binds the class.
1942
+
1943
+ ## Registry
1944
+
1945
+ `tenant_registry` in the features D1 inventories tenant names and application
1946
+ state; Cloudflare's object listing does not include those fields. Beside it,
1947
+ `tenant_operations` holds one receipt per lifecycle operation
1948
+ ([Lifecycle operations](#lifecycle-operations)). The edge
1949
+ upserts a row from the object's wake report. The object repeats the
1950
+ report on later responses until the edge acknowledges a successful registry
1951
+ write, so a transient D1 outage does not lose inventory or migration failures.
1952
+
1953
+ Each report carries a generation and a strictly increasing sequence, stored
1954
+ atomically with the report in the object's local KV. The sequence advances on
1955
+ every wake and migration retry, including pre-migration progress markers, even
1956
+ when timestamps are identical. The edge updates an existing row only when its
1957
+ generation matches and the report sequence is higher. Delayed or repeated
1958
+ reports cannot replace newer health, schema versions, or errors. An
1959
+ acknowledgement consumes only the exact current report, including its generation
1960
+ and sequence. Unordered RPC failures preserve rows that already have an ordered
1961
+ health report. PITR installs a fresh report generation together with the outbox
1962
+ fence; reconciliation republishes the recovered object's health under that
1963
+ generation. Dump restore installs the same fresh generation. Failed preparation
1964
+ restores the previous report fence, and explicit abandonment republishes current
1965
+ health under its recovery generation.
1966
+
1967
+ | Column | Meaning |
1968
+ |---|---|
1969
+ | `state` | `active`, `migrating`, `failed`, `frozen`, `archived`, `purged`. Wake reports never overwrite `frozen`, `archived` or `purged`. |
1970
+ | `schema_version` | Applied tenant migrations |
1971
+ | `report_generation`, `report_sequence` | Report ordering fence (initially `initial`) and last accepted sequence (initially `0`) |
1972
+ | `last_pre_migration_bookmark` | PITR bookmark taken before the last migration |
1973
+ | `last_error` | The last migration error, or null |
1974
+ | `tenant_id`, `partition_key` | The organization, and the partition key for partition objects (`id` is the object name) |
1975
+ | `last_backup_at`, `last_backup_key` | The last finished backup |
1976
+ | `outbox_seq` | The last ordered-lane outbox entry (lookup, registry) the edge applied |
1977
+ | `jurisdiction` | The objects' jurisdiction |
1978
+
1979
+ Fan out over every object with `forEachTenant` from `src/lib/tenants.ts`;
1980
+ `syncTenants(env)` drains every object's outbox with it — an operator or manual
1981
+ sweep: nothing needs it on a schedule, since every alarm asks the edge to drain
1982
+ its own object. It skips `archived` and
1983
+ `purged` tenants, runs at most `concurrency` at a time (default 4), and
1984
+ reports each tenant's failure instead of throwing:
1985
+
1986
+ {/* doc-compile: skip — generated-project code */}
1987
+ ```ts
1988
+ import { forEachTenant } from "../lib/tenants";
1989
+
1990
+ const results = await forEachTenant(env, async (tenantId, stub) => {
1991
+ return tenantId;
1992
+ }, { concurrency: 8 });
1993
+ ```
1994
+
1995
+ ## Operator routes
1996
+
1997
+ The edge mounts tenant operations at `<api>/tenants` (e.g. `/api/v1/tenants`).
1998
+ They are plain Hono routes: they are not in the OpenAPI document or the MCP
1999
+ tool list.
2000
+
2001
+ **`tenancy.operator.http`** decides which of them exist. Generating the
2002
+ lifecycle helpers never implies exposing them over HTTP:
2003
+
2004
+ ```ts
2005
+ tenancy: {
2006
+ isolation: 'durable-object',
2007
+ // No generated operator routes. Your own `operator:` actions call the
2008
+ // helpers in src/lib/tenants.ts (archiveTenant, restoreTenant, purgeTenant, …).
2009
+ operator: { http: false },
2010
+ }
2011
+ ```
2012
+
2013
+ ```ts
2014
+ tenancy: {
2015
+ isolation: 'durable-object',
2016
+ // Only these routes are mounted; nothing else answers under <api>/tenants.
2017
+ operator: { http: { allow: ['archive', 'unarchive', 'sync', 'retry-migration'] } },
2018
+ }
2019
+ ```
2020
+
2021
+ Route names are the path segments below: `retry-migration`, `archive`,
2022
+ `unarchive`, `purge`, `sync`, `rebuild-lookups`, `schedules` (the GET plus
2023
+ `arm`, `hold` and `arm-all`), `lookups-migrate`, `outbox-receipts`, `backup`,
2024
+ `backups` (the list plus `backups/counts`), `bookmark`, `restore`,
2025
+ `cancel-restore`. An unknown name, an empty list, or `http` set beside the
2026
+ deprecated `operator.purge` fails the build (`TENANCY_OPERATOR_HTTP`). An
2027
+ allowlist that mounts any mutation (every name but `backups`, `bookmark`,
2028
+ `outbox-receipts`) needs `auth.cloudflareAccess` covering `<api>/tenants`;
2029
+ without it the build fails (`TENANCY_OPERATOR_AUTH`): a sysadmin session cookie
2030
+ is not enough authority for a lifecycle mutation. With
2031
+ `http: false` no `src/tenant/admin.ts` is generated and `src/index.ts` mounts
2032
+ nothing at `<api>/tenants`; `src/lib/tenants.ts` is unchanged. Leaving `http`
2033
+ unset mounts every route and warns: the default becomes `false` in the next
2034
+ breaking release.
2035
+ Every route needs a sysadmin (`user.role === 'sysadmin'`, Better Auth admin
2036
+ plugin). With `auth.cloudflareAccess` configured, the caller must also come
2037
+ through Cloudflare Access, and the build fails (`TENANCY_ADMIN_NOT_BEHIND_ACCESS`)
2038
+ unless an Access application covers both the path and the API host (the
2039
+ hostnames in `providers.runtime.config.routes` and `domain`; with none
2040
+ configured, only an application without `hosts` covers it).
2041
+
2042
+ | Route | Effect |
2043
+ |---|---|
2044
+ | `POST /tenants/:id/retry-migration` | Clear the reset count and migrate the object again; records the new report |
2045
+ | `GET /tenants/operations/:operationId` | The durable receipt of a lifecycle operation, settled from the object's receipt or the registry when it was left `requested` / `uncertain`. See [Lifecycle operations](#lifecycle-operations). |
2046
+ | `POST /tenants/:id/provision` | The only route that creates a tenant object. Refuses an id that is not a Better Auth organization (`404 TENANT_ORGANIZATION_UNKNOWN`) and a partition name; wakes the organization's object so it migrates and reports, registers it from that report, returns the registry row. Idempotent: a registered organization is returned as is. Use it to move an existing organization into a tenant object (provision, then `archive`, `backup`, `restore`, `sync`, `unarchive`). Partition objects are created by their first request, never here. |
2047
+ | `POST /tenants/:id/archive` | The object answers `423 TENANT_ARCHIVED`; `tenant_registry.state` → `archived` (`forEachTenant` skips it). Data is kept. Refuses a purged object, and refuses an unknown id (`TENANT_NOT_PROVISIONED`) **without waking it**: no lifecycle operation but `provision` creates an object. If archive fails after the object archived (for example the registry write failed), retry it: it re-records the object's own report, which says archived. The other operator routes (`unarchive`, `sync`, `backup`, `backups`, `retry-migration`, `restore`) likewise act on registered objects only. When the edge drains queued work from an object it has not registered, it records the state the object reports, `archived` included, never `active` by default. |
2048
+ | `POST /tenants/:id/unarchive` | Serve again; state → `active`. Registered objects only: an unknown id is refused (`TENANT_NOT_PROVISIONED`) without waking it, as is a purged one. Refuses (`TENANT_RESTORE_PENDING`) while a restore is pending or not yet reconciled by `POST /tenants/:id/sync`, or while an unconfirmed restore or stranded maintenance fence awaits `POST /tenants/:id/cancel-restore` — the explicit last step of [restore quarantine](#restore-quarantine). |
2049
+ | `POST /tenants/:id/purge` | Body `{ "confirm": "<id>" }`. `archived` tenants only: records the current point-in-time bookmark in `tenant_registry.last_purge_bookmark`, records the durable purge marker in the control object, erases the object (`deleteAlarm()`, then `deleteAll()`), marks it `purged`; the object answers `410 TENANT_PURGED` from then on. Resumable: after an error, retry it ([interrupted purges](#hard-deletes-and-the-audit-log)). Any other state, or a wrong `confirm`, answers `409`. |
2050
+
2051
+ **`tenancy.operator.purge`** (deprecated: name `'purge'` in `operator.http.allow`,
2052
+ or leave it out). When your own code imports `purgeTenant` from
2053
+ `lib/tenants` (an organization-delete flow that archives, cleans up platform
2054
+ rows and storage, then erases the object; a named import, `export *` or a
2055
+ named re-export, or a namespace / dynamic import of `lib/tenants` in a file that
2056
+ names `purgeTenant`; type-only imports and comments do not count),
2057
+ the raw purge route is **not mounted**: an operator could otherwise erase an object behind your flow's back.
2058
+ It does not exist at all then (`404`), and `purgeTenant` stays available to your
2059
+ code. Set `tenancy.operator: { purge: true }` to mount it anyway, or
2060
+ `{ purge: false }` to leave it out when nothing imports `purgeTenant`. An
2061
+ `operator.http.allow` list that names `'purge'` mounts it regardless of what
2062
+ your code imports: the list is the explicit opt-in.
2063
+
2064
+ Purge is not immediate erasure: Durable Object point-in-time recovery keeps
2065
+ the data for 30 days after `deleteAll()`. Purge is still final as far as these
2066
+ routes go. No route brings a purged tenant back: restore and unarchive refuse it,
2067
+ and the marker is never cleared. `tenant_registry.last_purge_bookmark` records
2068
+ the bookmark from just before the purge. Getting the data back means restoring
2069
+ that bookmark and clearing the control object's marker in your own code; no
2070
+ generated route does either.
2071
+
2072
+ The same operations are functions in `src/lib/tenants.ts`: `provisionTenantTarget`,
2073
+ `retryTenantMigration`, `archiveTenant`, `unarchiveTenant`, `purgeTenant`.
2074
+
2075
+ ### Lifecycle operations
2076
+
2077
+ Every mutation above runs through one executor, `runTenantOperatorOperation`
2078
+ in `src/lib/tenants.ts`, against one registry, `TENANT_OPERATIONS`. The
2079
+ registry is the state machine: which `tenant_registry.state` an operation may
2080
+ start from, what it leaves, and whether the caller must confirm.
2081
+
2082
+ | Operation | From | To | Confirm |
2083
+ |---|---|---|---|
2084
+ | `provision` | no row | the object's own report (`active`, `migrating`, `failed`) | |
2085
+ | `archive` | `active`, `migrating`, `failed`, `frozen` | `archived` | |
2086
+ | `unarchive` | `archived` | `active` | |
2087
+ | `purge` | `archived` | `purged` | `{ confirm: "<id>" }` |
2088
+ | `restore` | `archived` | `archived` (pending) | |
2089
+ | `cancel-restore` | `archived` | `archived` | `{ confirm: "<id>" }` |
2090
+ | `retry-migration`, `sync`, `rebuild-lookups`, `backup`, `schedules.arm`, `schedules.hold` | any registered state but `purged` | unchanged | |
2091
+ | `schedules.arm-all`, `lookups.migrate` | not bound to one tenant | | |
2092
+ | `backups`, `bookmark`, `outbox-receipts`, `schedules.status` | reads: registered, not `purged` | | |
2093
+
2094
+ The executor runs, in order: the registry read and the transition check
2095
+ (`409 TENANT_INVALID_TRANSITION`, `404 TENANT_NOT_PROVISIONED`), the
2096
+ confirmation (`409 TENANT_CONFIRM_REQUIRED`), the `begin` audit row (a failed
2097
+ write is `503 TENANT_AUDIT_UNAVAILABLE` and **nothing runs**), the operation,
2098
+ then the outcome row. All of that happens before the tenant object is woken, so
2099
+ an invalid transition never creates or touches an object. Reads skip the audit.
2100
+
2101
+ Every mutation has an **operation id** and a **durable receipt**. Send yours as
2102
+ `X-Quickback-Operation-Id` (8–128 characters of `[A-Za-z0-9_-]`, else
2103
+ `400 TENANT_OPERATION_ID_INVALID`) or let the route mint one; the response
2104
+ carries it as `operationId`. The receipt is a `tenant_operations` row in the
2105
+ features D1, written `requested` before the object is touched and settled
2106
+ `completed` or `failed` after, with the operation's parameters hash, actor,
2107
+ `actorAuthMethod`, `fromState`, `resultingState`, error code and the recorded
2108
+ response (≤ 4000 characters). Every audit row of the operation carries the same
2109
+ `operationId` in `metadata`, with `phase: requested | completed | failed |
2110
+ uncertain`. If the outcome cannot be recorded after the operation ran, the
2111
+ receipt says `uncertain`, never a false `completed`.
2112
+
2113
+ Repeating an id **with the same parameters** replays the recorded outcome
2114
+ without running again (`replayed: true` in the response; a recorded failure is
2115
+ thrown again). The same id with different parameters is `409
2116
+ TENANT_OPERATION_ID_CONFLICT`; an id whose receipt is still `requested` or
2117
+ `uncertain` is `409 TENANT_OPERATION_PENDING` until it is reconciled.
2118
+
2119
+ `GET /tenants/operations/:operationId` (also `reconcileTenantOperation(env,
2120
+ id)` in `src/lib/tenants.ts`) returns the receipt and settles a `requested` or
2121
+ `uncertain` one from durable evidence: the object's own last-operation receipt
2122
+ (archive and unarchive record the operation id atomically with their change),
2123
+ else the registry state the operation leaves (`resultingState`; an open
2124
+ `restore_session` for a restore). A settled receipt records `reconciledBy` and
2125
+ gains its missing `completed` audit row with `reconciled: true`. Without
2126
+ evidence the receipt is returned unchanged (`evidence: 'none'`) for a human to
2127
+ decide.
2128
+
2129
+ Your own `operator:` action uses the same executor, so an authored control
2130
+ plane and the generated routes cannot drift:
2131
+
2132
+ {/* doc-compile: skip — generated-project code */}
2133
+ ```ts
2134
+ import { archiveTenant, runTenantOperatorOperation } from "../../../lib/tenants";
2135
+
2136
+ export default defineAction({
2137
+ path: "/ops/archive-org",
2138
+ method: "POST",
2139
+ input: z.object({ organizationId: z.string(), operationId: z.string().optional() }),
2140
+ access: { userRole: ["sysadmin"], authMethod: ["cloudflare-access"] },
2141
+ operator: { target: { table: "organizations", by: "input.organizationId" } },
2142
+ async execute({ env, ctx, input }) {
2143
+ return runTenantOperatorOperation({
2144
+ env, ctx,
2145
+ tenantId: input.organizationId,
2146
+ operation: "archive",
2147
+ operationId: input.operationId,
2148
+ execute: ({ operationId }) => archiveTenant(env, input.organizationId, { operationId }),
2149
+ });
2150
+ },
2151
+ });
2152
+ ```
2153
+
2154
+ With `tenancy.operator.http: false` this is the only way lifecycle mutations
2155
+ happen, and it carries the same transition check, confirmation, audit rows and
2156
+ operation id as the generated routes would.
2157
+
2158
+ **Target resolvers.** Three functions in `src/lib/tenants.ts` separate naming a
2159
+ tenant from creating one, so no ordinary operation can wake an object for an
2160
+ identifier nobody owns:
2161
+
2162
+ | Function | Admits | Never |
2163
+ |---|---|---|
2164
+ | `resolveTenantTarget(env, id)` | A registered, unpurged object (`404 TENANT_NOT_PROVISIONED`, `410 TENANT_PURGED` otherwise) | Creates state or wakes the object |
2165
+ | `provisionTenantTarget(env, organizationId)` | An organization that exists in Better Auth (`404 TENANT_ORGANIZATION_UNKNOWN`); wakes and registers it; idempotent | A partition name; an id Better Auth does not know |
2166
+ | `resolveRecoveryTarget(env, id)` | A registered row **including purged** (with `lastPurgeBookmark`), for your own exceptional recovery action | An unknown id |
2167
+
2168
+ A partition name `<orgId>:<key>` is trusted through the registry's own
2169
+ ownership columns, not by parsing the name: a row registered to another
2170
+ organization is `409 TENANT_TARGET_MISMATCH`. `runTenantOperatorOperation`
2171
+ applies the same check to every operation.
2172
+
2173
+ ## FGA
2174
+
2175
+ With [`authz.fga`](/define/fga), `fga_tuples` is a table of every organization's
2176
+ object. It is not in the platform D1.
2177
+
2178
+ - `ctx.fga` (`check`, `listObjects`, `expand`, `read`, `write`) exists in the
2179
+ actions of tenant features. It reads and writes that organization's tuples
2180
+ in the object, for a caller who is a member of the organization. A delete
2181
+ is visible to the next check.
2182
+ - The edge hydrates no `ctx.fga`. It forwards `/fga/v1/*` to the caller's
2183
+ organization object, like a tenant route (no organization: `400 TENANT_REQUIRED`).
2184
+ - Tuples never cross organizations. Two organizations can hold tuples for the
2185
+ same object id, and each sees only its own.
2186
+
2187
+ These shapes are refused, because each would read or write tuples from
2188
+ somewhere other than the organization object:
2189
+
2190
+ | Code | Cause |
2191
+ |---|---|
2192
+ | `TENANCY_FGA_SHARING` | `authz.fga.sharing` is set. Share tokens and links are opened on the edge without a session. You can still write a `user:*` tuple with `ctx.fga` in a tenant action, but only members of that organization can read it: `/fga/v1` needs a signed-in member, and platform actions have no `ctx.fga`. A public page must read the app's own tables instead, such as a share-token table. |
2193
+ | `TENANCY_FGA_MEMBERSHIP` | `authz.fga.membership` is set. Those tuples are written from Better Auth hooks on the edge. Write the tuples from a tenant action instead. |
2194
+ | `TENANCY_FGA_ACCESS_ARM` | A table, action, room binding or `realtime.wsTicket` declares an `access: { fga }` arm. Call `ctx.fga.check(...)` in a tenant action instead. |
2195
+ | `TENANCY_FGA_MIXED` | A platform feature's action, or an action in a [partitioned](#partitions) feature, reads `ctx.fga`. A partition object's database holds no tuples. |
2196
+
2197
+ Moving to `'durable-object'` does not copy the tuples already in the features
2198
+ D1. `fga_tuples` leaves the platform schema, so the next generated D1
2199
+ migration may drop it. If you need the existing tuples, copy them into each
2200
+ organization's object before you apply that migration.
2201
+
2202
+ ## What the compiler refuses
2203
+
2204
+ | Code | Cause |
2205
+ |---|---|
2206
+ | `TENANT_ORGANIZATION_UNKNOWN` / `TENANT_TARGET_MISMATCH` / `TENANT_PURGED` | Runtime: `provision` of an id Better Auth does not know; a partition name the registry attributes to another organization; a normal operation on a purged row (recovery uses `resolveRecoveryTarget`). |
2207
+ | `TENANT_OPERATION_ID_CONFLICT` / `TENANT_OPERATION_PENDING` | Runtime: a repeated operation id with different parameters; a repeated id whose receipt is not yet settled (reconcile it with `GET /tenants/operations/:id`). |
2208
+ | `TENANT_INVALID_TRANSITION` / `TENANT_CONFIRM_REQUIRED` / `TENANT_OPERATION_ID_INVALID` | Runtime, not compile: a lifecycle operation refused by the state machine, without its confirmation, or with a malformed operation id. See [Lifecycle operations](#lifecycle-operations). |
2209
+ | `TENANCY_OPERATOR_AUTH` | `tenancy.operator.http.allow` names a mutation route but `auth.cloudflareAccess` is not configured. Configure Access, allow only `backups` / `bookmark` / `outbox-receipts`, or set `http: false`. |
2210
+ | `TENANCY_OPERATOR_HTTP` | `tenancy.operator.http` is neither `false` nor `{ allow: [...] }` naming at least one known route, or it is set beside the deprecated `tenancy.operator.purge`. See [Operator routes](#operator-routes). |
2211
+ | `TENANCY_RUNTIME` / `TENANCY_PROVIDER` | The runtime is not Cloudflare, or the database is not `cloudflare-d1`. Postgres schemas, RLS and migrations do not port to Durable Object SQLite. |
2212
+ | `TENANCY_ORGANIZATIONS` | The Better Auth organization plugin is off. |
2213
+ | `TENANCY_PLACEMENT_CROSS_TENANT` | An organization-scoped table declares `placement: 'platform'`. Use `{ platform: true, crossTenant: true }`. |
2214
+ | `TENANCY_PLACEMENT_UNSCOPED` | A table declares `placement: 'tenant'` but no arm of its firewall — top level, `all:`, `any:` or `optional` — binds an organization column. The tenant pin needs one. |
2215
+ | `TENANCY_PLACEMENT_UNCONFIRMED` | The build carries no deployed-schema facts (an older CLI, or an unreadable latest snapshot), and a table derives `tenant` from an `any:` / optional organization arm. Declare its placement. |
2216
+ | `TENANCY_ORG_COLUMNS` | A tenant table's firewall binds more than one organization column. Keep it on the platform (`{ platform: true, crossTenant: true }`). |
2217
+ | `TENANCY_PLACEMENT_MOVED` | A table in the deployed features D1 derives `tenant` from its firewall (a shared project switching to `'durable-object'`, or an `any:` / optional organization arm). Declare `placement: 'tenant'` after copying its rows, or `{ platform: true, crossTenant: true }`. See [Placement changes on deployed tables](#placement-changes-on-deployed-tables). |
2218
+ | `TENANCY_PLACEMENT_MIXED_FEATURE` | One feature mixes tenant and platform tables. |
2219
+ | `TENANCY_FK_TENANT_TO_PLATFORM` | A tenant table references a platform table. References to Better Auth tables (`user`) are ids without a foreign key and are allowed. |
2220
+ | `TENANCY_FK_PLATFORM_TO_TENANT` | A platform table references a tenant table. |
2221
+ | `TENANCY_ASYNC_TRANSACTION` | A tenant action, a helper it reaches, or a JS trigger handler passes an async or Promise-returning callback to `transaction()` on a db / tx handle. |
2222
+ | `TENANCY_BATCH_ASYNC` | A tenant table's `create` / `update` / `upsert` access, or its `guards`, is a function. |
2223
+ | `TENANCY_UNSAFE_RECREATE` | A new tenant migration recreates a referenced table or copies into an unsafe NOT NULL column. |
2224
+ | `TENANCY_UNSAFE_ACTION` / `TENANCY_ROOT_ACTION` / `TENANCY_CTX_UNAVAILABLE` | A tenant action is cross-tenant `unsafe` (`unsafe: true`, or an object without `crossTenant: false`) or sets `unsafe.authWrites`, mounts outside its feature's path (and outside every [tenant namespace](#tenant-namespaces) prefix), or reads `ctx.auth`, `ctx.tenancy`, `ctx.mintScope` or `ctx.seal` — or `ctx.fga` when the project declares no `authz.fga` — by property access or destructuring, including the `auth` execute param. They exist only on the edge. The `ctx` check also covers helpers tenant code imports and JS trigger handlers on tenant tables. Keep cross-tenant `unsafe` and root-path ingress in a platform feature and call a [result job](#result-jobs). `unsafe: { reason, crossTenant: false }` is allowed: see [Same-tenant unsafe actions](#same-tenant-unsafe-actions). |
2225
+ | `TENANCY_QUEUE_BINDING` | Tenant code (an action, a tenant job, a JS trigger handler or a helper they import) enqueues to a binding that is not one of the edge Worker's queues, or one the build cannot read. See [Platform queues](#platform-queues). |
2226
+ | `TENANCY_ENV_UNAVAILABLE` | A tenant action, a tenant job's body, a helper either imports, or a JS trigger handler on a tenant table reads an `env` binding (`env.DB`, `c.env.AUTH_DB`, `const { BUCKET } = env`, …). The tenant Worker has no D1, R2, KV, queue, var or secret bindings. |
2227
+ | `TENANCY_HELPER_UNRESOLVED` | A module tenant code loads imports a relative or alias path that names no file in the build, or uses a computed `import()` / `require()`. See [Helpers run where their caller runs](#helpers-run-where-their-caller-runs). |
2228
+ | `TENANCY_TRIGGER_UNVERIFIABLE` | A JS `handler:` trigger on a tenant table has a source that can't be extracted as one arrow function or function expression. |
2229
+ | `TENANCY_JOB_CALL_TENANT_SOURCE` | `callTenantJob`'s tenant argument is not visibly server-verified (`ctx.activeOrgId` / `ctx.tenantId`, a `resolveTenant` / `resolvePrincipalTenant` result, a `forEachTenant` callback's tenant). Opt out with `// quickback-allow-tenant-source: <reason>`. See [Result jobs](#result-jobs). |
2230
+ | `TENANCY_JOB_RESULT_SCHEMA` / `TENANCY_JOB_RESULT_PRODUCER` | A result job without `resultSchema` (or a `resultSchema` without `result: true`), a `resultSchema` that is not a stripping or strict `z.object`, a `result` that is not the literal `true`, a result job that is not a tenant job or a project without `isolation: 'durable-object'`; or a result-job message built anywhere but `callTenantJob`'s message argument. See [Result jobs](#result-jobs). |
2231
+ | `TENANCY_ADMISSION_DEPENDENCY` | Edge code reads a tenant-placed table: a scope kind, namespace, ws-ticket, live view, platform feature's authorization, derived JSON key, or a platform action's anchor, refs or operator target. Also a platform action, feature `lib/` file, schedule, non-tenant queue handler, or edge-loaded `quickback/lib` helper or auth hook naming a tenant table, an edge module importing a tenant feature's module or using a computed `import()` / `require()`, an ambiguous scope instance, or an unresolved instance on a kind that is also a lookup. At runtime, an edge query on a tenant table throws `TENANT_TABLE_ON_EDGE`. See [Admission tables stay on the platform](#admission-tables-stay-on-the-platform). |
2232
+ | `TENANCY_ADMISSION_MIXED_PLACEMENT`, `_PARTITIONED`, `_UNRESOLVED_INSTANCE`, `_TENANT_COLUMN`, `_LOOKUP`, `_SQL_HELPER`, `_SELF`, `_HOPS` | A scope kind reads a tenant table but can't be tenant-backed. See [Which kinds can be tenant-backed](#which-kinds-can-be-tenant-backed). |
2233
+ | `TENANCY_LEGACY_SCOPE_ENTER`, `TENANCY_LEGACY_SCOPE_MINT` | A scope kind reading a tenant table is admitted through `POST /scope/v1/enter` only, or has a `subject: 'supplied' \| 'both'` role. Permanent: use instance-bound OAuth with `subject: 'user'` roles. |
2234
+ | `TENANCY_NAMESPACE_SPLIT`, `_PARTITIONED`, `_UNROUTED`, `_MINT` | See [Tenant namespaces](#tenant-namespaces). |
2235
+ | `TENANCY_EDGE_ACTION_PLACEMENT`, `_NAMESPACE`, `_CTX` | An `edge: true` action is in a tenant feature, is not under a tenant namespace prefix, or reads `ctx.<exposeAs>`. See [Edge namespace actions](#edge-namespace-actions). |
2236
+ | `TENANCY_TICKET_GATE_UNSUPPORTED` | A `realtime.wsTicket` session gate on a tenant room isn't the tenant-backed kind's own admission, plus at most one `{ roles }` lane of plain organization roles. See [Durable Objects → Tenant rooms](/platform/realtime/durable-objects#tenant-rooms). |
2237
+ | `TENANCY_ROOM_LOOKUP` | A resource-backed realtime room (`bindings.durableObjects[].access.resource`) on a tenant table has no `tenancy.lookups` entry on its room key column. See [Durable Objects → Tenant rooms](/platform/realtime/durable-objects#tenant-rooms). |
2238
+ | `TENANCY_ROOM_UNSUPPORTED` | A realtime room on a tenant table uses a form the tenant gate can't run: multi-resource `access.resources`, a partitioned table, or an inherited `read.access` with a `record:` predicate. |
2239
+ | `TENANCY_ADMISSION_ID_STRATEGY` | A tenant-backed scope kind's instance or proving table has `generateId: false \| 'short' \| 'serial'`, `allowClientIds: true`, or a numeric primary key (see [Tenant-backed scope kinds](#tenant-backed-scope-kinds)). Or tenant code (an action, a helper it reaches, or a trigger handler) inserts into a scope instance or proving table with an explicit `id`, a spread that may carry one, or a row it can't inspect. Omit `id`; `// quickback-allow-id` is honored only for `crypto.randomUUID()` / `generateId(…)`. |
2240
+ | `TENANCY_REALTIME_PLATFORM_ROOM` | With a tenant-backed scope kind, a tenant table's CRUD broadcasts (`realtime.scopeTable` / `scopeKeyFrom`) target a room that is not on a tenant table, or the ws-ticket's bound kind is tenant-backed but its `scopeTable` is a platform table. A tenant object can address only rooms on its own tables. |
2241
+ | `TENANCY_REALTIME_TAG_AMBIGUOUS` | A tenant-backed kind proves subjects from more than one table, and a recipients resolver calls `recipient.scope({ kind, subjectId })` for it (or with a `kind` the compiler can't read) without `provingTable`, so the tenant tag can't name the proving table. The error lists each call's file and line. Pass `provingTable`. |
2242
+ | `REALTIME_RECIPIENT_PROVING_TABLE` | A recipients resolver's `recipient.scope` names a literal `provingTable` that is not one of the kind's proving tables (a relationship `from` of its roles). Any tenancy mode. |
2243
+ | `TENANCY_REALTIME_VIEW_ROOM` | A live view is rooted on a tenant table while a scope kind is tenant-backed. View rooms are not tenant-qualified yet. |
2244
+ | `TENANCY_LEGACY_SCOPE_TICKET` | `realtime.wsTicket` accepts supplied-scope principals (`acceptScope`) for a tenant room or a tenant-backed kind. A legacy scope claim carries no tenant, so its ticket cannot name a tenant room. |
2245
+ | `TENANCY_UNSUPPORTED` | A tenant table declares `embeddings`, `namespace`, `owns`, an `.encrypted()` / `.sealed()` column, or a `q.storageKey()` column. |
2246
+ | `TENANCY_TRIGGER_CROSS_OBJECT` | A tenant table's `sql:` trigger (body or `when:`) names a table outside its own object — a platform table, another partition kind, or a table no feature declares — or uses SQL the compiler does not model (a schema-qualified name, a CTE, a table-valued function other than `json_each` / `json_tree`, a statement keyword such as `DROP` / `PRAGMA`, unbalanced parentheses). Also a platform table's trigger that names a tenant table. Every violation is listed. |
2247
+ | `TENANCY_BACKUP` | `tenancy.backup.bucket` is not an UPPER_SNAKE binding name, or `every` is not `<n>m` / `<n>h` / `<n>d` of at least 15 minutes. |
2248
+ | `TENANCY_LOOKUP` | A lookup's table is not a tenant table, or its column is not a column of that table. |
2249
+ | `TENANCY_PARTITION` / `TENANCY_PARTITION_UNSCOPED` / `TENANCY_PARTITION_KEY` / `TENANCY_PARTITION_KINDS` | A partition name is not a lowercase identifier, the table has no organization arm, the key is not a column (or differs within the feature), or the project declares more than one partition kind. |
2250
+ | `TENANCY_FK_CROSS_PARTITION` / `TENANCY_CROSS_PARTITION` | A foreign key, or an action (or a helper it reaches, or a trigger handler), spans two objects. |
2251
+ | `TENANCY_QUEUE_PARTITION` / `TENANCY_QUEUE_MIXED_PLACEMENT` | A queue handler imports a partitioned feature or mixes database placements. Split the job into supported handlers. |
2252
+ | `TENANCY_QUEUE_TENANT_ID` / `TENANCY_QUEUE_RESERVED` | A platform action, queue handler or schedule builds a tenant-job message without `tenantId`, or a handler uses the reserved type `qb:backup`. |
2253
+ | `TENANCY_NAMESPACE_DELETION` | See [Deleting the namespace](#deleting-the-namespace). |
2254
+ | `TENANCY_JURISDICTION_CHANGED` / `TENANCY_JURISDICTION_UNKNOWN` | `tenancy.jurisdiction` differs from the deployed `wrangler.toml`'s `# quickback:tenancy.jurisdiction=` line, or `wrangler.toml` binds `QuickbackTenant` without that line. Add it with the jurisdiction the objects were created in. A build without `wrangler.toml` only warns. |
2255
+ | `TENANCY_ROUTE_RESERVED` / `TENANCY_ADMIN_NOT_BEHIND_ACCESS` | A feature mounts at `/tenants`, or Access is configured and no application covers the operator routes. |
2256
+ | `TENANCY_TENANT_WORKER_UNKNOWN` | The existing `wrangler.toml` references `QuickbackTenant` in a form the build cannot resolve to an edge and tenant Worker. Rewrite it as plain `[[durable_objects.bindings]]` tables under a named edge table. |
2257
+ | `TENANCY_TENANT_WORKER_CHANGED` | A deployed edge (per the existing `wrangler.toml`) would bind a different tenant Worker than it does now. See [Two Workers](#two-workers). |
2258
+ | `TENANCY_ENVIRONMENT_WORKER` / `TENANCY_ENVIRONMENT_SHARED` / `TENANCY_ENVIRONMENT_BACKUP` | A named environment has no `tenantWorker.name`, shares a tenant Worker or backup bucket with another target, or names a tenant Worker like an edge or files Worker. A target that does not deploy as the project `name` reuses the single-target tenant Worker or bucket. A Worker takes a reserved `<name>-unselected`, `<name>-files-unselected` or `<name>-tenant-unselected` placeholder name. `backupBucketName` is missing while `tenancy.backup` is set, or set while it is not. See [Named environments](#named-environments). |
2259
+ | `TENANCY_PURGE_DO` / `TENANCY_CHANGES` / `TENANCY_FGA` | `tenancy.purge`, `changes`, or a top-level `fga` block (declare it at `authz.fga`) together with `isolation: 'durable-object'`. |
2260
+ | `TENANCY_FGA_SHARING` / `TENANCY_FGA_MEMBERSHIP` / `TENANCY_FGA_ACCESS_ARM` / `TENANCY_FGA_MIXED` | An FGA shape that would reach tuples from outside the organization object. See [FGA](#fga). |
2261
+
2262
+
2263
+ ### Fence a result job to an authorization epoch
2264
+
2265
+ `callTenantJob(env, tenantId, message, runId, { expectedAuthorizationEpoch })`
2266
+ optionally requires a safe nonnegative integer epoch. The tenant compares it
2267
+ with its live admission permit before executing **or replaying** a result. A
2268
+ mismatch returns `{ status: 'unavailable', code: 'TENANT_AUTHORIZATION_EPOCH_CHANGED' }`.
2269
+ The expected epoch also participates in the durable run hash: reusing a run ID
2270
+ with a different fence produces `TENANT_JOB_RUN_CONFLICT` once admitted.
2271
+
2272
+ Result handlers receive readonly `authorizationEpoch?: number` from that same
2273
+ permit, including ordinary four-argument calls. This value never comes from the
2274
+ message. Preserve it in a server-owned proof when subsequent work must be
2275
+ invalidated by restore. Other queue handlers may omit it. This does not change
2276
+ archive, restore or purge admission. RPC version 8 is required; deploy the tenant
2277
+ worker before the edge worker. Older workers fail closed on the new contract.
2278
+
2279
+
2280
+ ### Fence purge to a retained backup
2281
+
2282
+ Operators retaining records before erasure can use
2283
+ `purgeTenant(env, tenantId, tenantId, { expectedBackup: { key, generation, bytes } })`.
2284
+ Pass the completed archived backup receipt whose contents were retained. The
2285
+ options and receipt accept exactly those keys. The receipt must name this
2286
+ organization's backup and contain a positive safe integer byte count. This
2287
+ fence does not download bytes and has no backup-download size cap.
2288
+
2289
+ Under exclusive control admission, before permanent purge marking, the tenant
2290
+ requires that receipt to match its latest completed archived backup, current
2291
+ generation and clean state. A completed restore, subsequent writes after
2292
+ unarchive, or a replacement backup refuse with `TENANT_PURGE_BACKUP_STALE`.
2293
+ Nothing is erased and a known rejected fence is released. In-flight work or
2294
+ restore continues to refuse under the existing maintenance contract.
2295
+
2296
+ The permanent purge marker retains the receipt identity outside erased tenant
2297
+ storage. A retry with that same receipt can finish after an interrupted erase;
2298
+ a different receipt, or a fenced retry of an originally unfenced purge, refuses.
2299
+ The original three-argument trusted-operator API remains available, including
2300
+ finishing an already marked purge without supplying a receipt. It cannot alter
2301
+ the permanent receipt or re-enable the tenant. Applications requiring retention
2302
+ must consistently supply the fourth argument before their first irreversible
2303
+ purge. RPC version 9 is required: deploy the tenant worker before the edge worker;
2304
+ older workers fail closed. No room-deletion callback or general maintenance
2305
+ callback is exposed by this API.
2306
+
2307
+
2308
+ ### Hold admission through a resource room's native commit
2309
+
2310
+ Result jobs and outbox delivery do not keep a permit around their consumer's
2311
+ later native Durable Object commit. For a declared, locally authored room on a
2312
+ non-partitioned tenant resource, call `acquireTenantRoomPermit` **inside the
2313
+ actual room operation**, while holding its own work gate:
2314
+
2315
+ ```ts no-compile
2316
+ import { tenantRoomSession } from "../../../lib/tenant-room-session";
2317
+ import { acquireTenantRoomPermit, releaseTenantRoomPermit } from "../../../lib/tenants";
2318
+
2319
+ // Method on the existing room class. No FIFO, admission, name initialization,
2320
+ // or native storage I/O here: control calls back while this actor awaits it.
2321
+ getTenantRoomSession(version: number) {
2322
+ return tenantRoomSession(this.ctx, version);
2323
+ }
2324
+
2325
+ // Inside the actual authorized room operation, after taking its work gate:
2326
+ const permit = await acquireTenantRoomPermit(this.env, verifiedTenantId, this.ctx, {
2327
+ binding: "PAGE_ROOM",
2328
+ key: roomKey,
2329
+ operationId, // stable server-owned id for THIS operation's exact retries
2330
+ expectedAuthorizationEpoch,
2331
+ });
2332
+ // All SQL authority reads, binary checks and native transaction retries must
2333
+ // settle here. Keep the existing resource-pointer/native CAS checks.
2334
+ await commitNativeCheckpoint();
2335
+ await this.ctx.storage.sync();
2336
+ await releaseTenantRoomPermit(this.env, this.ctx, permit);
2337
+ ```
2338
+
2339
+ Do not put release in an unconditional `finally`: a timeout, failed sync or
2340
+ unsettled continuation is not proof that no native commit can still happen.
2341
+ An ambiguous acquire/release retains quarantine; retry that exact operation or
2342
+ prove the actual room actor was replaced. A new operation must have its own ID.
2343
+ Released/denied identities remain terminal in individual durable records; the
2344
+ shared index contains only active operations. Delayed acquisition cannot
2345
+ resurrect them. Exact concurrent retries share the final ownership outcome;
2346
+ late failed cleanup cannot release a grant another retry already received.
2347
+ Duplicate requests wait on their own bounded timer, never another request's
2348
+ I/O promise. Timing out does not release admission.
2349
+
2350
+ The tenant verifies the live actor session through the declared existing room
2351
+ namespace, the current epoch/generation, and exactly one undeleted resource row
2352
+ using its parsed organization/key/deletion columns. It returns captured
2353
+ `authorizationEpoch`, `generation` and the permit token. This is ownership and
2354
+ restore admission, not user authorization: keep the application's operator/user
2355
+ checks and resource-pointer CAS. Ordinary admitted jobs can still change a
2356
+ resource while this permit is held; the permit blocks exclusive restore, purge
2357
+ and backup maintenance, not ordinary application edits.
2358
+
2359
+ The public helper takes the actual native `DurableObjectState` and derives its
2360
+ private session; it does not accept a supplied session string. An edge caller
2361
+ with a made-up object gets a different UUID and cannot borrow the live room
2362
+ session merely by reading the callback. Release also requires that same actual
2363
+ state/session. A session is private to that actor instance, never persisted or
2364
+ a module-wide UUID shared by rooms. `tenantRoomSession` uses a WeakMap keyed by
2365
+ its actual DurableObjectState and performs no I/O. Pruning compares the live
2366
+ room session, not the tenant actor's session. Tenant/control restart, elapsed
2367
+ time, a missing method or a probe error never retire a live room permit. An
2368
+ actual room replacement proves that its old continuation cannot access native
2369
+ storage. It may still finish external I/O; immutable R2/artifact safety remains
2370
+ a separate application protocol. See [DO shutdown semantics](https://developers.cloudflare.com/durable-objects/concepts/durable-object-lifecycle/)
2371
+ and [storage sync/output gates](https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/).
2372
+
2373
+ Room records and an armed compatibility guard are stored atomically outside
2374
+ the tenant's restored database. Older control code sees a non-purge operation
2375
+ with an unknown recovery kind and refuses restore, purge and recovery. It cannot
2376
+ prune the separate room records. Only the room-aware release or a proven room
2377
+ restart clears the last active record and its guard together. Unknown or
2378
+ inconsistent state blocks admission and exclusive maintenance. RPC version 10
2379
+ is required; room permit calls never fall back to an older protocol. Rolling
2380
+ back while a room permit is held intentionally retains quarantine.
2381
+
2382
+ The compiler adds private tenant-worker bindings to **existing edge room
2383
+ classes**, with the matching edge script for each named environment. It adds no
2384
+ room class, namespace or migration. External-script rooms, partitioned resource
2385
+ rooms and rooms without a provable parsed organization column cannot use this
2386
+ API. Authored tenant handlers still cannot read the private bindings. Deploying
2387
+ a tenant that references a previously undeployed edge class may require the
2388
+ existing edge class to be deployed first. For an upgrade, a compatibility phase
2389
+ can add the zero-I/O `getTenantRoomSession` method using a private per-instance
2390
+ UUID to the **already existing** edge room class before introducing the tenant's
2391
+ reverse binding or the full room-permit configuration. Then the room-aware
2392
+ tenant can bind that existing class, followed by the full edge configuration. The full room class must then use
2393
+ the same generated WeakMap helper for both its callback and acquisition; a
2394
+ compatibility-only private UUID must not remain a different identity source.
2395
+ This is an artifact/rollout plan, not a deployment performed by compilation.
2396
+
2397
+ A completely fresh pair has circular edge `TENANT` and tenant `ROOM` references.
2398
+ Its account bootstrap/provisioning order needs a separate account-stage drill;
2399
+ local generation and Wrangler dry-run do not prove that one deployment creates
2400
+ such a pair without extra setup. Named-environment bindings must target that
2401
+ specific environment's existing edge Worker/class, and the deployment must
2402
+ verify those physical namespaces before enabling room commits. No raw SQL
2403
+ opener or arbitrary callback bridge is added.
2404
+ Local fault-adapter tests can drop an RPC reply before helper validation or
2405
+ reject an application acknowledgement after native `storage.sync()` completed.
2406
+ Those seams do not establish physical network loss or a native storage engine
2407
+ failure; the corresponding native/account failure drills remain open.