@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.11

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 (222) hide show
  1. package/package.json +32 -26
  2. package/skill/SKILL.md +46 -15
  3. package/skill/references/app-setup.md +43 -12
  4. package/skill/references/dev.md +5 -2
  5. package/skill/references/endpoint.md +39 -28
  6. package/skill/references/errors.md +50 -37
  7. package/skill/references/files.md +8 -4
  8. package/skill/references/jobs.md +39 -7
  9. package/skill/references/table-and-migration.md +47 -3
  10. package/skill/references/tests.md +73 -16
  11. package/skill/references/webhooks-links-connectors.md +1 -1
  12. package/src/build-recipe.ts +198 -0
  13. package/src/build.ts +60 -4
  14. package/src/bun.ts +181 -13
  15. package/src/cloudflare/application.ts +822 -0
  16. package/src/cloudflare/bindings.ts +159 -0
  17. package/src/cloudflare/export.ts +621 -0
  18. package/src/cloudflare/import.ts +888 -0
  19. package/src/cloudflare/maintenance.ts +518 -0
  20. package/src/cloudflare/names.ts +16 -0
  21. package/src/cloudflare/ops.ts +375 -0
  22. package/src/cloudflare/r2-files.ts +172 -0
  23. package/src/cloudflare/restore.ts +167 -0
  24. package/src/cloudflare/tracker.ts +192 -0
  25. package/src/cloudflare.ts +100 -146
  26. package/src/contract/app-id.ts +5 -0
  27. package/src/contract/artifact-schema.ts +9 -1
  28. package/src/contract/build.ts +40 -2
  29. package/src/contract/capability-cases.ts +30 -0
  30. package/src/contract/compile.ts +1 -0
  31. package/src/contract/containers.ts +19 -0
  32. package/src/contract/context.ts +35 -9
  33. package/src/contract/declaration.ts +2 -0
  34. package/src/contract/defaults.ts +27 -4
  35. package/src/contract/define.ts +29 -3
  36. package/src/contract/index.ts +1 -0
  37. package/src/contract/kit.ts +4 -1
  38. package/src/contract/platform.ts +3 -2
  39. package/src/contract/vocabulary.ts +26 -8
  40. package/src/dev/changes.ts +5 -43
  41. package/src/dev/contract-digest.ts +17 -0
  42. package/src/dev/index.ts +1 -1
  43. package/src/dev/launcher.ts +197 -41
  44. package/src/dev/output.ts +13 -3
  45. package/src/dev/wire.ts +11 -1
  46. package/src/disk-assets.ts +8 -3
  47. package/src/files/archive.ts +2 -2
  48. package/src/files/handle.ts +2 -1
  49. package/src/files/job-names.ts +12 -0
  50. package/src/files/kinds.ts +74 -32
  51. package/src/files/scan.ts +3 -4
  52. package/src/files/streams.ts +3 -1
  53. package/src/implement/anonymous.ts +12 -11
  54. package/src/implement/boot.ts +84 -27
  55. package/src/implement/bounded.ts +21 -2
  56. package/src/implement/capability.ts +16 -4
  57. package/src/implement/dispatch.ts +423 -178
  58. package/src/implement/failures.ts +59 -4
  59. package/src/implement/faults.ts +5 -1
  60. package/src/implement/index.ts +1 -0
  61. package/src/implement/invocation.ts +62 -11
  62. package/src/implement/principal.ts +25 -2
  63. package/src/implement/terminals.ts +93 -0
  64. package/src/implement/tokens.ts +4 -2
  65. package/src/implement/types.ts +22 -4
  66. package/src/implement/workload.ts +42 -16
  67. package/src/jobs/mail.ts +8 -0
  68. package/src/jobs/report.ts +5 -1
  69. package/src/jobs/runner.ts +702 -126
  70. package/src/jobs/schedule.ts +7 -1
  71. package/src/jobs/scrub.ts +14 -1
  72. package/src/jobs/types.ts +6 -0
  73. package/src/spa-fallback.ts +12 -0
  74. package/src/testing/endpoint-access.ts +493 -202
  75. package/src/testing/index.ts +1 -1
  76. package/src/testing/isolation.ts +8 -1
  77. package/src/testing/kit.ts +86 -4
  78. package/src/testing/policy-isolation.ts +2 -2
  79. package/src/testing/proxy.ts +15 -10
  80. package/types/src/agent-skill.d.ts +29 -0
  81. package/types/src/build-recipe.d.ts +70 -0
  82. package/types/src/build.d.ts +29 -0
  83. package/types/src/bun.d.ts +99 -0
  84. package/types/src/client/caller.d.ts +19 -0
  85. package/types/src/client/contract.d.ts +131 -0
  86. package/types/src/client/error-reporting.d.ts +66 -0
  87. package/types/src/client/index.d.ts +4 -0
  88. package/types/src/client/rpc.d.ts +14 -0
  89. package/types/src/client/share.d.ts +2 -0
  90. package/types/src/client/transport.d.ts +42 -0
  91. package/types/src/cloudflare/application.d.ts +73 -0
  92. package/types/src/cloudflare/bindings.d.ts +33 -0
  93. package/types/src/cloudflare/export.d.ts +16 -0
  94. package/types/src/cloudflare/import.d.ts +47 -0
  95. package/types/src/cloudflare/maintenance.d.ts +117 -0
  96. package/types/src/cloudflare/names.d.ts +11 -0
  97. package/types/src/cloudflare/ops.d.ts +81 -0
  98. package/types/src/cloudflare/r2-files.d.ts +9 -0
  99. package/types/src/cloudflare/restore.d.ts +9 -0
  100. package/types/src/cloudflare/tracker.d.ts +29 -0
  101. package/types/src/cloudflare.d.ts +43 -0
  102. package/types/src/contract/app-id.d.ts +2 -0
  103. package/types/src/contract/artifact-schema.d.ts +10 -0
  104. package/types/src/contract/attachment.d.ts +41 -0
  105. package/types/src/contract/build.d.ts +12 -0
  106. package/types/src/contract/capability-cases.d.ts +9 -0
  107. package/types/src/contract/compile.d.ts +11 -0
  108. package/types/src/contract/connect.d.ts +51 -0
  109. package/types/src/contract/containers.d.ts +3 -0
  110. package/types/src/contract/context.d.ts +525 -0
  111. package/types/src/contract/declaration.d.ts +307 -0
  112. package/types/src/contract/defaults.d.ts +228 -0
  113. package/types/src/contract/define.d.ts +376 -0
  114. package/types/src/contract/file.d.ts +44 -0
  115. package/types/src/contract/group.d.ts +274 -0
  116. package/types/src/contract/handled.d.ts +18 -0
  117. package/types/src/contract/index.d.ts +20 -0
  118. package/types/src/contract/kit.d.ts +211 -0
  119. package/types/src/contract/platform.d.ts +9 -0
  120. package/types/src/contract/problems.d.ts +14 -0
  121. package/types/src/contract/redirect.d.ts +25 -0
  122. package/types/src/contract/schema-from-shape.d.ts +10 -0
  123. package/types/src/contract/schema-shape.d.ts +5 -0
  124. package/types/src/contract/snapshot-source.d.ts +15 -0
  125. package/types/src/contract/token.d.ts +58 -0
  126. package/types/src/contract/vocabulary.d.ts +32 -0
  127. package/types/src/contract/webhook-binding.d.ts +24 -0
  128. package/types/src/contract/webhook-scheme.d.ts +23 -0
  129. package/types/src/dev/changes.d.ts +7 -0
  130. package/types/src/dev/contract-digest.d.ts +1 -0
  131. package/types/src/dev/index.d.ts +2 -0
  132. package/types/src/dev/launcher.d.ts +32 -0
  133. package/types/src/dev/output.d.ts +28 -0
  134. package/types/src/dev/wire.d.ts +126 -0
  135. package/types/src/disk-assets.d.ts +6 -0
  136. package/types/src/errors.d.ts +46 -0
  137. package/types/src/fetch.d.ts +7 -0
  138. package/types/src/files/archive.d.ts +26 -0
  139. package/types/src/files/clamscan.d.ts +32 -0
  140. package/types/src/files/handle.d.ts +107 -0
  141. package/types/src/files/job-names.d.ts +9 -0
  142. package/types/src/files/kinds.d.ts +112 -0
  143. package/types/src/files/scan.d.ts +78 -0
  144. package/types/src/files/sniff.d.ts +7 -0
  145. package/types/src/files/streams.d.ts +17 -0
  146. package/types/src/files/treatment.d.ts +18 -0
  147. package/types/src/from-row.d.ts +20 -0
  148. package/types/src/honeypot.d.ts +2 -0
  149. package/types/src/implement/anonymous.d.ts +24 -0
  150. package/types/src/implement/attachment.d.ts +14 -0
  151. package/types/src/implement/boot.d.ts +128 -0
  152. package/types/src/implement/bounded.d.ts +32 -0
  153. package/types/src/implement/browser-config.d.ts +19 -0
  154. package/types/src/implement/capability.d.ts +142 -0
  155. package/types/src/implement/challenge.d.ts +75 -0
  156. package/types/src/implement/client-address.d.ts +11 -0
  157. package/types/src/implement/connect.d.ts +67 -0
  158. package/types/src/implement/crashes.d.ts +31 -0
  159. package/types/src/implement/dispatch.d.ts +251 -0
  160. package/types/src/implement/egress.d.ts +14 -0
  161. package/types/src/implement/environment.d.ts +14 -0
  162. package/types/src/implement/failures.d.ts +58 -0
  163. package/types/src/implement/faults.d.ts +48 -0
  164. package/types/src/implement/headers.d.ts +7 -0
  165. package/types/src/implement/implement.d.ts +58 -0
  166. package/types/src/implement/index.d.ts +25 -0
  167. package/types/src/implement/invocation.d.ts +136 -0
  168. package/types/src/implement/membership.d.ts +201 -0
  169. package/types/src/implement/multipart.d.ts +36 -0
  170. package/types/src/implement/params.d.ts +7 -0
  171. package/types/src/implement/principal.d.ts +57 -0
  172. package/types/src/implement/project.d.ts +11 -0
  173. package/types/src/implement/public.d.ts +61 -0
  174. package/types/src/implement/serve.d.ts +25 -0
  175. package/types/src/implement/terminals.d.ts +33 -0
  176. package/types/src/implement/tokens.d.ts +49 -0
  177. package/types/src/implement/types.d.ts +263 -0
  178. package/types/src/implement/urls.d.ts +15 -0
  179. package/types/src/implement/verifiers.d.ts +19 -0
  180. package/types/src/implement/webhook.d.ts +55 -0
  181. package/types/src/implement/workload.d.ts +61 -0
  182. package/types/src/implement/xlsx.d.ts +6 -0
  183. package/types/src/index.d.ts +12 -0
  184. package/types/src/jobs/exception.d.ts +40 -0
  185. package/types/src/jobs/mail.d.ts +67 -0
  186. package/types/src/jobs/report.d.ts +56 -0
  187. package/types/src/jobs/runner.d.ts +218 -0
  188. package/types/src/jobs/schedule.d.ts +17 -0
  189. package/types/src/jobs/scrub.d.ts +12 -0
  190. package/types/src/jobs/types.d.ts +98 -0
  191. package/types/src/react/caller.d.ts +30 -0
  192. package/types/src/react/errors.d.ts +40 -0
  193. package/types/src/react/hooks.d.ts +110 -0
  194. package/types/src/react/index.d.ts +5 -0
  195. package/types/src/react/provider.d.ts +58 -0
  196. package/types/src/react/store.d.ts +68 -0
  197. package/types/src/react/testing.d.ts +28 -0
  198. package/types/src/react/types.d.ts +33 -0
  199. package/types/src/rpc/builder.d.ts +52 -0
  200. package/types/src/rpc/contract.d.ts +23 -0
  201. package/types/src/rpc/dispatcher.d.ts +11 -0
  202. package/types/src/rpc/types.d.ts +62 -0
  203. package/types/src/service/define.d.ts +42 -0
  204. package/types/src/service/index.d.ts +3 -0
  205. package/types/src/service/serve.d.ts +28 -0
  206. package/types/src/spa-fallback.d.ts +2 -0
  207. package/types/src/standard-schema.d.ts +55 -0
  208. package/types/src/testing/caller.d.ts +95 -0
  209. package/types/src/testing/challenge.d.ts +11 -0
  210. package/types/src/testing/dev.d.ts +97 -0
  211. package/types/src/testing/endpoint-access.d.ts +132 -0
  212. package/types/src/testing/index.d.ts +12 -0
  213. package/types/src/testing/isolation.d.ts +3 -0
  214. package/types/src/testing/kit.d.ts +207 -0
  215. package/types/src/testing/membership.d.ts +132 -0
  216. package/types/src/testing/policy-isolation.d.ts +113 -0
  217. package/types/src/testing/preload.d.ts +1 -0
  218. package/types/src/testing/proxy.d.ts +40 -0
  219. package/types/src/testing/runner.d.ts +8 -0
  220. package/types/src/testing/sample-file.d.ts +5 -0
  221. package/types/src/testing/status.d.ts +4 -0
  222. package/types/src/undumpable.d.ts +5 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/app",
3
- "version": "0.9.0-dev.1",
3
+ "version": "0.9.0-dev.11",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -14,87 +14,93 @@
14
14
  "files": [
15
15
  "src",
16
16
  "skill",
17
- "!src/**/__tests__/**"
17
+ "!src/**/__tests__/**",
18
+ "types"
18
19
  ],
19
20
  "exports": {
20
21
  ".": {
21
22
  "bun": "./src/index.ts",
22
- "types": "./src/index.ts",
23
+ "types": "./types/src/index.d.ts",
23
24
  "default": "./src/index.ts"
24
25
  },
25
26
  "./bun": {
26
27
  "bun": "./src/bun.ts",
27
- "types": "./src/bun.ts",
28
+ "types": "./types/src/bun.d.ts",
28
29
  "default": "./src/bun.ts"
29
30
  },
30
31
  "./cloudflare": {
31
32
  "bun": "./src/cloudflare.ts",
32
- "types": "./src/cloudflare.ts",
33
+ "types": "./types/src/cloudflare.d.ts",
33
34
  "default": "./src/cloudflare.ts"
34
35
  },
35
36
  "./contract": {
36
37
  "bun": "./src/contract/index.ts",
37
- "types": "./src/contract/index.ts",
38
+ "types": "./types/src/contract/index.d.ts",
38
39
  "default": "./src/contract/index.ts"
39
40
  },
40
41
  "./client": {
41
42
  "bun": "./src/client/index.ts",
42
- "types": "./src/client/index.ts",
43
+ "types": "./types/src/client/index.d.ts",
43
44
  "default": "./src/client/index.ts"
44
45
  },
45
46
  "./react": {
46
47
  "bun": "./src/react/index.ts",
47
- "types": "./src/react/index.ts",
48
+ "types": "./types/src/react/index.d.ts",
48
49
  "default": "./src/react/index.ts"
49
50
  },
50
51
  "./react/testing": {
51
52
  "bun": "./src/react/testing.ts",
52
- "types": "./src/react/testing.ts",
53
+ "types": "./types/src/react/testing.d.ts",
53
54
  "default": "./src/react/testing.ts"
54
55
  },
55
56
  "./implement": {
56
57
  "bun": "./src/implement/index.ts",
57
- "types": "./src/implement/index.ts",
58
+ "types": "./types/src/implement/index.d.ts",
58
59
  "default": "./src/implement/index.ts"
59
60
  },
60
61
  "./service": {
61
62
  "bun": "./src/service/index.ts",
62
- "types": "./src/service/index.ts",
63
+ "types": "./types/src/service/index.d.ts",
63
64
  "default": "./src/service/index.ts"
64
65
  },
65
66
  "./build": {
66
67
  "bun": "./src/build.ts",
67
- "types": "./src/build.ts",
68
+ "types": "./types/src/build.d.ts",
68
69
  "default": "./src/build.ts"
69
70
  },
70
71
  "./testing": {
71
72
  "bun": "./src/testing/index.ts",
72
- "types": "./src/testing/index.ts",
73
+ "types": "./types/src/testing/index.d.ts",
73
74
  "default": "./src/testing/index.ts"
74
75
  },
75
76
  "./testing/isolation": {
76
77
  "bun": "./src/testing/isolation.ts",
77
- "types": "./src/testing/isolation.ts",
78
+ "types": "./types/src/testing/isolation.d.ts",
78
79
  "default": "./src/testing/isolation.ts"
79
80
  },
80
81
  "./testing/preload": {
81
82
  "bun": "./src/testing/preload.ts",
82
- "types": "./src/testing/preload.ts",
83
+ "types": "./types/src/testing/preload.d.ts",
83
84
  "default": "./src/testing/preload.ts"
84
85
  },
85
86
  "./dev": {
86
87
  "bun": "./src/dev/index.ts",
87
- "types": "./src/dev/index.ts",
88
+ "types": "./types/src/dev/index.d.ts",
88
89
  "default": "./src/dev/index.ts"
89
90
  },
90
91
  "./dev/wire": {
91
92
  "bun": "./src/dev/wire.ts",
92
- "types": "./src/dev/wire.ts",
93
+ "types": "./types/src/dev/wire.d.ts",
93
94
  "default": "./src/dev/wire.ts"
94
95
  },
96
+ "./dev/changes": {
97
+ "bun": "./src/dev/changes.ts",
98
+ "types": "./types/src/dev/changes.d.ts",
99
+ "default": "./src/dev/changes.ts"
100
+ },
95
101
  "./agent-skill": {
96
102
  "bun": "./src/agent-skill.ts",
97
- "types": "./src/agent-skill.ts",
103
+ "types": "./types/src/agent-skill.d.ts",
98
104
  "default": "./src/agent-skill.ts"
99
105
  }
100
106
  },
@@ -103,14 +109,14 @@
103
109
  "test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
104
110
  },
105
111
  "dependencies": {
106
- "@fabrika/auth": "0.9.0-dev.1",
107
- "@fabrika/auth-core": "0.9.0-dev.1",
108
- "@fabrika/db": "0.9.0-dev.1",
109
- "@fabrika/email": "0.9.0-dev.1",
110
- "@fabrika/jwks": "0.9.0-dev.1",
111
- "@fabrika/platform": "0.9.0-dev.1",
112
- "@fabrika/platform-node": "0.9.0-dev.1",
113
- "@fabrika/proxy-core": "0.9.0-dev.1",
112
+ "@fabrika/auth": "0.9.0-dev.11",
113
+ "@fabrika/auth-core": "0.9.0-dev.11",
114
+ "@fabrika/db": "0.9.0-dev.11",
115
+ "@fabrika/email": "0.9.0-dev.11",
116
+ "@fabrika/jwks": "0.9.0-dev.11",
117
+ "@fabrika/platform": "0.9.0-dev.11",
118
+ "@fabrika/platform-node": "0.9.0-dev.11",
119
+ "@fabrika/proxy-core": "0.9.0-dev.11",
114
120
  "altcha-lib": "2.6.0",
115
121
  "jose": "^5.9.0"
116
122
  },
package/skill/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: fabrika-app
3
- version: 0.9.0-dev.1
3
+ version: 0.9.0-dev.11
4
4
  description: >
5
5
  How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
6
6
  slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors
@@ -30,6 +30,7 @@ below. When it does not reach far enough, declare the step off it. A declared st
30
30
  | `fabrika.contract.ts` | `app.contract((c) => ({ api: c.rpc('/api', { … }), … }))`: mounts the groups |
31
31
  | `src/app.ts` | `export default serve(contract, { database: scoped(tables) })` and nothing else |
32
32
  | `web/` | the SPA: React over `@fabrika/app/react` and `@fabrika/ui`, never a server module |
33
+ | `tools/` | a developer's tools, such as a command line; the application never loads them |
33
34
 
34
35
  ## The paved road
35
36
 
@@ -233,14 +234,15 @@ the access check. `references/spa.md` shows the stack.
233
234
  | an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to exactly those origins |
234
235
  | a signed link (unsubscribe) | `signs: ['<purpose>']` | `ctx.tokens.sign` |
235
236
  | a webhook binding | `binds: '<webhook>'` | `ctx.webhooks('<webhook>').bind` and `.unbind` |
236
- | a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')` |
237
+ | a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')`, `ctx.kick('<job>', { at })` |
237
238
  | a trigger, function or view | its migration | — |
238
239
 
239
- Scope every scoped table a raw statement reads with `${ctx.sql.scope(<capability>, '<table>', '<alias>')}`, a conjunct
240
- of its WHERE or JOIN … ON (`where (<filter>) and ${…}`): `ctx.target` for `on` and `in`, `ctx.within` for `over`, a
241
- job's minted `Ref` or `Within` with `tx.sql.scope`. It binds the capability's whole predicate, chain included, as the
242
- handles apply it, and on an `update` or `delete` target it needs that operation's action; a reference table needs
243
- none. A deviation is fine: declare it, and do not contort the code to avoid it. The approver sees every declaration
240
+ Scope every scoped table a raw statement reads with `${ctx.sql.scope(<capability>, '<table>', { alias: '<alias>' })}`,
241
+ a conjunct of its WHERE or JOIN … ON (`where (<filter>) and ${…}`): `ctx.target` for `on` and `in`, `ctx.within` for
242
+ `over`, a job's minted `Ref` or `Within` with `tx.sql.scope`. It binds the capability's whole predicate, chain
243
+ included, as the handles apply it. The table an `update` or `delete` writes takes `{ use: 'update' }` or
244
+ `{ use: 'delete' }`, which needs that operation's action; a reference table needs none. The runtime does not check
245
+ where you put a fragment: the approver reads it. A deviation is fine: declare it, and do not contort the code to avoid it. The approver sees every declaration
244
246
  marked "needs closer review". Do not hide reach in a helper; the runtime builds `ctx.sql` and `ctx.db.unscoped` only
245
247
  where they are declared. A query or an export declares only `'read'`.
246
248
 
@@ -255,10 +257,13 @@ Which promise the types, the checker, boot, the runtime or the approver keeps, a
255
257
  - An endpoint never sends e-mail; it has no `ctx.mail`. It records an outbox row, declares `kicks: ['<job>']` and calls `ctx.kick('<job>')`, which
256
258
  starts that job once its transaction committed. The job declares `mailer` and sends with `ctx.mail`, under a key
257
259
  derived from the row, and sends again only where `ctx.mail.mayRetry(error)` allows it (`references/jobs.md`).
258
- - No `as` (except `as const`), `any`, `@ts-ignore`, `@ts-expect-error`, `process.env` or `Bun.env`.
260
+ - No `as` (except `as const`), `any`, `@ts-ignore`, `@ts-expect-error`, `process.env` or `Bun.env`. A developer's tool
261
+ under `tools/` (a command line that calls a deployed environment with a service key) may read the environment and
262
+ spawn a process; it still has no `as`, `any` or key literal, the application never imports it, and `tools/` holds
263
+ no `package.json`. Its tests run in the platform build, so they test its logic, without a keychain or a network.
259
264
  - Never log an error object, a request, headers or the environment.
260
265
  - Never edit a generated file (`src/db/schema.generated.ts`, the generated tests, `fabrika/entry.generated.ts`,
261
- `fabrika/connect/`) or a committed migration. Regenerate the file; write a new migration.
266
+ `fabrika/migrations.generated.ts`, `fabrika/connect/`) or a committed migration. Regenerate the file; write a new migration.
262
267
 
263
268
  ## Ask the human first
264
269
 
@@ -295,11 +300,36 @@ bunx tsc --noEmit # once, at the end
295
300
  bunx fabrika-check . # once, after tsc; refusals fail; hints print below them
296
301
  ```
297
302
 
303
+ **On Cloudflare** (`fabrika.config.ts` imports `defineApp` from `@fabrika/provider-cloudflare`, as
304
+ `references/app-setup.md` shows) the application runs in one Durable Object over SQLite. Its `db/migrations/*.sql` are SQLite (`references/table-and-migration.md`), and the
305
+ object applies them when it boots, so there is no `migrate` and no command needs a database URL or `FABRIKA_APP_ID`.
306
+ The tests run on `@fabrika/db/testing-sqlite` (`references/tests.md`), in memory, and never skip. A handler holds the
307
+ object's transaction, so its `limits.timeoutMs` is at most 25 s. A job's is at most 14 minutes, its default: longer
308
+ work claims a bounded batch per run, and the next run takes the rest (`references/jobs.md`). `ctx.sql` is SQLite there
309
+ (`references/endpoint.md`). No `scan: true`: the checker, the deploy and the boot refuse it. A migration names no
310
+ `fabrika_*` table but `REFERENCES fabrika_files (id)`. The deploy serves each SPA mount's
311
+ built `dir` itself; declare no `assets` on the Worker (`references/app-setup.md`).
312
+
313
+ The object runs one transaction at a time, so every `await` in a handler that may write holds the whole environment:
314
+ IAM, R2, a `fetch`, a `ctx.connect` call, a binding. One 2 s call caps the environment at half a request a second. A
315
+ query holds no transaction: each of its statements runs on its own, so two of its reads may see different committed
316
+ states. Inside a
317
+ mutation keep I/O to the framework's own: IAM, and the file it writes. A slow outside call goes into a row, the
318
+ mutation calls `ctx.kick('<job>')`, and the job makes the call outside `ctx.transaction` (`references/jobs.md`). The
319
+ checker hints on a mutation that declares `egress` or `connect` (`cloudflare-held-call`), and refuses
320
+ `DEFAULT CURRENT_TIMESTAMP` in a migration (`cloudflare-current-timestamp`).
321
+
322
+ ```bash
323
+ bunx fabrika db new <slug> # a new SQLite migration file
324
+ bunx fabrika db codegen # applies the migrations in memory; writes src/db/schema.generated.ts
325
+ bunx fabrika db test-scaffold # the generated tests, on @fabrika/db/testing-sqlite
326
+ bun test --isolate # no database URL; then tsc and fabrika-check as above
327
+ ```
328
+
298
329
  A generated file changes only through its command (`codegen`, `test-scaffold`); running it is the loop, not an edit.
299
330
  Format and lint only the files you wrote, with the repository's own tools: in the fabrika-platform repository
300
- `bunx dprint fmt <files>` and `bunx biome lint <files>`, never `biome check` (its formatter fights dprint), and never a
301
- generated file. An application outside that repository has neither configuration: use the formatter its own
302
- repository configures, or none, and never add a configuration unasked; tsc and `fabrika-check` are its gates. `FABRIKA_APP_ID` is lowercase letters, digits and `-`. An applied file is immutable: while you still
331
+ `bunx dprint fmt <files>` and `bunx oxlint <files>`, and never a generated file. An application outside that
332
+ repository has neither configuration: use the formatter its own repository configures, or none, and never add a configuration unasked; tsc and `fabrika-check` are its gates. `FABRIKA_APP_ID` is lowercase letters, digits and `-`. An applied file is immutable: while you still
303
333
  change an uncommitted migration, migrate into a fresh schema with another `FABRIKA_APP_ID`. Read a refusal's
304
334
  "allowed form" and use it; fix hints too. `references/errors.md` explains the findings and the type errors.
305
335
 
@@ -326,9 +356,10 @@ e-mails them, a link holder's files, HR's review with its history.
326
356
 
327
357
  ## Not built yet
328
358
 
329
- - The data layer runs on Bun and Postgres only (Zerops). On Cloudflare an application has no tables, jobs or files.
330
- - Jobs are cron only and app-wide: no `ctx.jobs.enqueue`, no job per scope. A `ctx.kick` starts a run of its job; it
331
- carries nothing, and the job finds its work in a queue table with `claim`. A list write is off the road (`sql`).
359
+ - On Cloudflare, where the application runs in one Durable Object over its SQLite and its `db/migrations/*.sql` are
360
+ SQLite, a file kind with `scan: true` is refused. Everything else on the road runs there.
361
+ - Jobs are cron only and app-wide: no `ctx.jobs.enqueue`, no job per scope. A `ctx.kick` starts a run of its job, now
362
+ or at `{ at }`; it carries nothing, and the job finds its work in a queue table with `claim`. A list write is off the road (`sql`).
332
363
  - A read across tables (a join, a filter over a related table, an aggregate over several) is off the road (`sql`).
333
364
  - An MCP workspace has no shell, so `codegen` and `test-scaffold` cannot run there. Tell the human; never write a
334
365
  generated file by hand.
@@ -19,22 +19,22 @@ the SPA is added with it.
19
19
  "test": "bun test --isolate"
20
20
  },
21
21
  "dependencies": {
22
- "@fabrika/app": "0.9.0-dev.1",
23
- "@fabrika/db": "0.9.0-dev.1",
24
- "@fabrika/provider-zerops": "0.9.0-dev.1",
25
- "@fabrika/proxy-core": "0.9.0-dev.1",
26
- "@fabrika/ui": "0.9.0-dev.1",
22
+ "@fabrika/app": "0.9.0-dev.11",
23
+ "@fabrika/db": "0.9.0-dev.11",
24
+ "@fabrika/provider-zerops": "0.9.0-dev.11",
25
+ "@fabrika/proxy-core": "0.9.0-dev.11",
26
+ "@fabrika/ui": "0.9.0-dev.11",
27
27
  "kysely": "0.29.6",
28
28
  "react": "^19.0.0",
29
29
  "react-dom": "^19.0.0",
30
30
  "zod": "^3.25.76"
31
31
  },
32
32
  "devDependencies": {
33
- "@fabrika/check": "0.9.0-dev.1",
34
- "@fabrika/cli": "0.9.0-dev.1",
35
- "@fabrika/platform": "0.9.0-dev.1",
33
+ "@fabrika/check": "0.9.0-dev.11",
34
+ "@fabrika/cli": "0.9.0-dev.11",
35
+ "@fabrika/platform": "0.9.0-dev.11",
36
36
  "@happy-dom/global-registrator": "^20.11.2",
37
- "@types/bun": "latest",
37
+ "@types/bun": "^1.4.3",
38
38
  "@types/react": "^19.0.0",
39
39
  "@types/react-dom": "^19.0.0",
40
40
  "typescript": "^5.9.3"
@@ -249,6 +249,35 @@ The platform's build runs the tests, writes the entrypoint, runs `fabrika-check`
249
249
  run `fabrika db migrate`, `fabrika db codegen --verify` and `fabrika db test-isolation` before the server starts: a
250
250
  version does not go live until every generated test passes. It writes every `FABRIKA_*` variable; never set one.
251
251
 
252
+ ## The deploy surface (Cloudflare)
253
+
254
+ ```ts fabrika.config.ts
255
+ import { defineApp } from '@fabrika/provider-cloudflare'
256
+
257
+ export default defineApp({ id: 'tasks' })
258
+ ```
259
+
260
+ That is the whole config. `defineApp` builds the application Worker: named after the id, running
261
+ `fabrika/entry.generated.ts`, with no route and no public URL, and IAM bound at its application entrypoint. The deploy
262
+ builds the proxy Worker from `fabrika.contract.ts` and writes the application's Durable Object, its files bucket, its
263
+ cron trigger and every `FABRIKA_*` variable; Control writes the IAM schema from the approved contract. Declare none of
264
+ them: a config that does is refused. Write no `resources`, `schema` or `pipeline.workerDir` (the config's directory is
265
+ the default). A binding of the application's own, or another `compatibility_date` or `compatibility_flags`, goes in
266
+ `worker: { bindings, compatibility_date, compatibility_flags }`; `IAM` stays the platform's. `package.json` names
267
+ `@fabrika/provider-cloudflare` where the Zerops one names `@fabrika/provider-zerops`, the entry is written by
268
+ `fabrika app build --provider=cloudflare` (the deploy runs it again from the pinned commit), and there is no
269
+ `zerops.yaml`.
270
+
271
+ It also serves the SPA: the deploy copies the build directory of each SPA and
272
+ link mount (`dir`, a link's `spa`) into `fabrika/assets/` at the mount's prefix (`/admin` into `fabrika/assets/admin/`)
273
+ after `pipeline.build`, and binds it as `ASSETS`. A `.assetsignore` at the root of a mount's directory excludes files
274
+ as it does for wrangler (gitignore syntax, relative to that directory); `.git`, `.hg`, `.svn` and `.bzr` are never
275
+ copied. A deploy whose mount directory the build did not write fails and
276
+ names the mount. A config that composes its own Worker with `resources` and declares `assets` keeps them instead, and the object reads each
277
+ request path from that directory as it is (`/admin/app.js` is `admin/app.js` there), so a hand-written `assets` works
278
+ only for a root mount, or for mounts whose directories nest like their prefixes; it needs `binding: 'ASSETS'` and
279
+ `run_worker_first: true`.
280
+
252
281
  ## The SPA (added when the application has one)
253
282
 
254
283
  The SPA is React, built from the screens and hooks of the framework: `@fabrika/app/react` runs the typed client's
@@ -379,8 +408,9 @@ await Bun.write(
379
408
  `src/schemas.ts`, `src/shared/` and its own modules; never a slice, `src/db/` or a Bun or Node module. The plugin loads the
380
409
  contract without its handlers. A row type the screen declares (`Task` above) is checked against the answer where
381
410
  the rows are passed in.
382
- - The last step points the page's assets at the SPA's prefix (`/`): the mount answers `index.html` for every path
383
- under it, so a deep link such as `/tasks/<id>` renders. `define` gives React's production build.
411
+ - The last step points the page's assets at the SPA's prefix (`/`): the mount answers `index.html` for every page
412
+ route under it (a path without an extension, or a navigation), so a deep link such as `/tasks/<id>` renders; a
413
+ missing asset such as an old `chunk-….js` is 404. `define` gives React's production build.
384
414
  - `sourcemap: 'external'` writes each script's map beside it, and the page names none. The platform build uploads the
385
415
  maps to Operations for the release the page reports, so an error's frames show the original source; the mount
386
416
  never serves a `.map` file (404). Keep the maps external: `inline` would ship the source to every visitor.
@@ -397,4 +427,5 @@ await Bun.write(
397
427
 
398
428
  ## Ignored files
399
429
 
400
- `.gitignore`: `node_modules/`, `fabrika.manifest.json`, `/fabrika/entry.generated.ts`, `/dist/`.
430
+ `.gitignore`: `node_modules/`, `fabrika.manifest.json`, `/fabrika/entry.generated.ts`, `/dist/`, and on Cloudflare
431
+ `/fabrika/assets/`, where a deploy stages the SPA's files.
@@ -1,7 +1,8 @@
1
1
  # references/dev.md — previewing the application with `fabrika app dev`
2
2
 
3
3
  `bunx fabrika app dev` serves the application on `http://127.0.0.1:3000/` through its test kit: the proxy decision,
4
- the stand-in IAM, a throwaway schema of `FABRIKA_TEST_POSTGRES_URL`, and each SPA from its build (run
4
+ the stand-in IAM, a throwaway schema of `FABRIKA_TEST_POSTGRES_URL` (on Cloudflare an in-memory SQLite database,
5
+ without a URL), and each SPA from its build (run
5
6
  `bun run build:web` first). Use it to look at the screens, never in place of a test.
6
7
 
7
8
  ## The seed
@@ -52,7 +53,9 @@ export default seed
52
53
  - Check every call the seed makes: an endpoint that refuses answers a status, and the seed goes on without its data.
53
54
  Throw when one does: a seed that throws stops `app dev` and prints its error with the stack.
54
55
  - `dev.runJob('<job>')` runs a cron job from the seed (`app dev` runs none on its schedule). A job's `ctx.links` works:
55
- the stand-in IAM takes the job's own key. What a job's handler throws is printed with its stack, here only.
56
+ the stand-in IAM takes the job's own key. What a request's 5xx or a job attempt threw is printed with its stack, here
57
+ only, after the log line that names its code and reason: your handler's own error, or a framework refusal with its
58
+ own message (a refused `ctx.sql` names its line).
56
59
 
57
60
  ## Outside the application
58
61
 
@@ -144,7 +144,11 @@ copyToTask: r.mutation({
144
144
  (`on` 404, `in` and `over` 403).
145
145
  - The handler binds each with `ctx.db.on(…)`, `ctx.db.in(…)` or `ctx.db.over(…)`. It has no `ctx.target`,
146
146
  `ctx.within`, `ctx.db.app`, `ctx.members` or `ctx.links`.
147
- - The generated tests add a denied case per capability. A join or a lock over many rows still needs `sql`.
147
+ - The `from` fields are gone from `input`, as under a single `on` or `in`: `input.toTaskId` is a type error. Each id
148
+ is its capability's value, `ctx.capabilities.to.value`.
149
+ - The generated tests add a denied case per capability, except an `over` one whose action another one needs on its
150
+ dimension, a container of it or a dimension inside it: every caller that passes that one is answered the list. Two
151
+ capabilities may share an action. A join or a lock over many rows still needs `sql`.
148
152
 
149
153
  ### The methods of each handle
150
154
 
@@ -188,9 +192,10 @@ picker of the org a new project goes into; an `'all'` caller types the org inste
188
192
  - `list({ where, orderBy, limit, after })` answers `{ items, next }`: a keyset page of at most `limit` rows (50 by
189
193
  default, 500 at most). Pass `next` back as `after`; it is `null` on the last page.
190
194
  - `where` is AND of `[column, operator, value]`: `=`, `<>`, `<`, `<=`, `>`, `>=`, `in` and `not in` (a list),
191
- `like`, `ilike`, `not like`, `not ilike`, `contains`. Optional filters are conditional spreads, each tuple
195
+ `like`, `ilike`, `not like`, `not ilike`, `contains`, and `is` and `is not` with `null` on a nullable column
196
+ (`['processed_at', 'is', null]`). Optional filters are conditional spreads, each tuple
192
197
  `as const` (`list` in `SKILL.md`): `...(input.status === undefined ? [] : [['status', '=', input.status] as const])`.
193
- There is no `is null` and no OR: write that in `ctx.sql`.
198
+ There is no OR: write that in `ctx.sql`. `count` and a queue table's `claim` (`references/jobs.md`) take the same `where`.
194
199
  - `orderBy` is `[[column, 'asc' | 'desc']]`; the key is added last as the tiebreak.
195
200
  - `count({ where })` answers a number. `aggregate({ groupBy, count, sum, min, max })` takes lists of column names
196
201
  and answers one row per group: the `groupBy` columns, `count` as a string (Postgres `bigint`), and `sum_<column>`,
@@ -406,7 +411,7 @@ export const workloadRows = (
406
411
  count(*) filter (where t.status <> 'done')::int as open,
407
412
  count(*) filter (where t.status <> 'done' and t.due_on < current_date)::int as overdue
408
413
  from tasks t
409
- where ${sql.scope(org, 'tasks', 't')}
414
+ where ${sql.scope(org, 'tasks', { alias: 't' })}
410
415
  and (${status}::text is null or t.status::text = ${status})
411
416
  group by t.assignee
412
417
  order by t.assignee`
@@ -420,8 +425,8 @@ export const workloadRows = (
420
425
 
421
426
  ## Raw SQL: `sql: 'read'`
422
427
 
423
- Raw SQL is legitimate for a join, a report, an `OR` or `IS NULL` filter, or a bulk write. Declare it on the endpoint;
424
- `ctx.sql` exists only there.
428
+ Raw SQL is legitimate for a join, a report, an `OR` filter, or a bulk write. Declare it on the endpoint;
429
+ `ctx.sql` exists only there. It runs on Postgres and, on Cloudflare, on SQLite (the rules of each are below).
425
430
 
426
431
  ```ts src/reports/endpoints.ts
427
432
  import { attachment } from '@fabrika/app/contract'
@@ -475,7 +480,7 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
475
480
  const rows = await ctx.sql(TaskExportRow)`
476
481
  select t.title, t.status, t.assignee, t.due_on::text as due_on
477
482
  from tasks t
478
- where ${ctx.sql.scope(ctx.target, 'tasks', 't')}
483
+ where ${ctx.sql.scope(ctx.target, 'tasks', { alias: 't' })}
479
484
  order by t.title
480
485
  limit 10000`
481
486
  await ctx.db.target.project_exports.insert({ row_count: rows.length })
@@ -487,7 +492,7 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
487
492
  - Every `${…}` of a value is a bound parameter, never SQL text. The one exception is `${ctx.sql.scope(…)}`: it is SQL
488
493
  (the predicate) around its own bound values, and it may have no value at all (`(true)`, `(false)`). Put no
489
494
  interpolation inside quotes, a quoted name, a dollar body or a comment: the tag refuses it.
490
- - **Scope every scoped table the statement reads with `${ctx.sql.scope(capability, '<table>', '<alias>')}`.**
495
+ - **Scope every scoped table the statement reads with `${ctx.sql.scope(capability, '<table>', { alias: '<alias>' })}`.**
491
496
  `ctx.sql` has no scope predicate of its own. The fragment is the capability's whole predicate on that table: for a
492
497
  `Ref` the object's column and every link of its chain, so a project moved to another org is out; for a `Within` its
493
498
  values, each container grant on its own column, every row for a global grant and none for an empty one. The
@@ -495,29 +500,31 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
495
500
  `Within` it minted to `tx.sql.scope`. A table the capability does not reach is a type error at the table name. A
496
501
  reference table is shared by every scope and needs no fragment, and no statement writes it. An application table
497
502
  needs none either (the intake job of `references/public-intake.md`).
498
- - **A fragment carries its action into the statement.** On the table an `update` or `delete` writes it needs the
499
- table's own update or delete action (`ctx.within('tasks.write', 'project')` for `update tasks`), so a read action
500
- never scopes a write. A column's own write action (`columns: { assignee: { write: 'tasks.assign' } }`) scopes an
501
- `update` too, when every column its `set` assigns declares that action: a table with only column writes is updated
502
- this way; anywhere else it needs an action the handles read the table with. `insert … on conflict do
503
- update … where ${…}` is an update of the inserted table. The fragment answers for its own query block: a CTE that
504
- updates and a statement that deletes take one capability each, and another occurrence of the written table (a
505
- subquery, `from tasks other`) reads with a read capability under its own alias. A refused fragment fails the call
506
- before anything is sent.
507
- - **A fragment is a conjunct.** It stands alone, joined by AND, at the top level of a WHERE or JOIN … ON clause whose
508
- top level holds no OR: `where (<the whole filter>) and ${…}`, `join projects p on p.id = t.project_id and ${…}`.
509
- The tag refuses `where a or ${…}`, `where a or b and ${…}`, `not ${…}`, a fragment in parentheses or outside such a
510
- clause. Never scope by hand with `ctx.target.value` alone: it drops the chain. The generated tests check that an `in`
511
- endpoint with `sql` leaks nothing of another scope.
503
+ - **A fragment states what it scopes.** `use` is `'read'` by default; the table an `update` or `delete` writes takes
504
+ `{ use: 'update' }` or `{ use: 'delete' }`, which needs the table's own update or delete action
505
+ (`ctx.within('tasks.write', 'project')` for `update tasks`) on a `'write'` site, so a read action never scopes a
506
+ write. A column's own write action (`columns: { assignee: { write: 'tasks.assign' } }`) is enough for `use: 'update'`
507
+ too; set only the columns it writes. `insert … on conflict do update … where ${…}` scopes the inserted table with
508
+ `use: 'update'`. Each block takes its own fragment: a CTE that updates and a statement that deletes take one
509
+ capability each, and another occurrence of the written table (a subquery, `from tasks other`) reads under its own
510
+ alias. A refused fragment fails the call before anything is sent.
511
+ - **A fragment is a conjunct.** Put it alone, joined by AND, at the top level of a WHERE or JOIN … ON clause whose top
512
+ level holds no OR: `where (<the whole filter>) and ${…}`, `join projects p on p.id = t.project_id and ${…}`. The tag
513
+ does not read where it stands, which relation it filters or which columns a `set` assigns: the approver does, and a
514
+ fragment under an `or` widens the statement to every row. Never scope by hand with `ctx.target.value` alone: it drops
515
+ the chain. The generated tests check that an `in` endpoint with `sql` leaks nothing of another scope.
512
516
  - Rows are parsed like `fromRow` (snake_case to camelCase), then by the schema. Postgres sends `bigint` and `numeric`
513
517
  as text: cast a count (`count(*)::int`), and a sum to the type its output declares (`::int` for an integer sum that
514
518
  fits, `::float8` for a fractional one), or keep it a string. A sum over no rows is `null`: `coalesce(sum(…), 0)`.
515
519
  - An optional filter is `(${value}::text is null or <column> = ${value})`.
516
520
  - One statement: `select`, `with`, `values`, plus `insert`, `update` and `delete` on a `'write'` site (a mutation, a
517
- job or a webhook). Refused before anything is sent: DDL, `SET`, `COPY`, transaction control, another schema, any
518
- `fabrika_*` or `pg_*` name, and calls outside the reviewed built-ins. A function your migrations declare is refused
519
- too: call it from a view. These name rules are defense in depth; the runtime role (DML only) is the boundary.
520
- - A query runs in a read-only transaction; a mutation's `ctx.sql` runs in the same transaction as its handles.
521
+ job or a webhook). Refused before anything is sent: DDL, `SET`, `COPY`, transaction control, and any `fabrika_*`
522
+ name. On Postgres also another schema, any `pg_*` name, and calls outside the reviewed built-ins; a function your migrations declare is refused too: call it from a view. On SQLite also any `sqlite_*`
523
+ name, `PRAGMA`, `ATTACH`, and a parameter you write yourself (`?`, `:x`, `@x`, `$x`): interpolate every value.
524
+ - On SQLite write SQLite: `count(*)` is already an integer, there is no `::` cast (`cast(x as text)`), and a list value
525
+ binds as JSON (`t.status in (select value from json_each(${list}))`).
526
+ - A query runs in a read-only transaction; a mutation's `ctx.sql` runs in the same transaction as its handles. A
527
+ `'read'` statement writes nothing, even in a mutation: one that tries fails the call.
521
528
 
522
529
  ## A file download: `attachment`
523
530
 
@@ -564,7 +571,7 @@ Every procedure takes `admission` (who may send it, how often) and `limits` (how
564
571
  | `admission.origins` | `'same-origin'` (default) or `'listed'` | `'same-origin'`, `'listed'` or `'any'` |
565
572
  | `admission.challenge` | none | `{ provider: 'altcha', secret, action?, cost?, maxAgeMs? }`, or `{ provider: 'turnstile', secret, siteKey, action? }` |
566
573
  | `limits.maxBytes` | 64 KiB, at most 1 MiB; with file fields 64 KiB plus each file at its kind's `maxBytes`, at most 48 MiB | the same |
567
- | `limits.timeoutMs` | 10 s, at most 60 s | the same |
574
+ | `limits.timeoutMs` | 10 s, at most 60 s; at most 25 s on Cloudflare | the same |
568
575
 
569
576
  - A declared `rate` merges into the default; `null` turns one bucket off. Past a bucket the answer is 429.
570
577
  - Every bucket is charged before the body is read and stays charged whatever the handler does. A bucket is a database
@@ -642,7 +649,7 @@ export const app = defineApp(vocabulary, tables, {
642
649
  - A public procedure updates or removes a row only by an id a verified token of its request carries, with
643
650
  `expectVersion`.
644
651
  - Single use and revocation are your state (a row the token names). The keys are the platform's: Control generates
645
- and rotates them, and an old key verifies until its last token expires. Cloudflare has no signed tokens.
652
+ and rotates them, and an old key verifies until its last token expires.
646
653
 
647
654
  ## Outside calls: `egress`
648
655
 
@@ -652,6 +659,10 @@ refused while the site runs (`capability_refused: undeclared_egress`). A public,
652
659
  none. The checker's `cross-app-fetch` accepts an absolute URL only under an origin some site declares. The approver
653
660
  sees every origin. The guard stops mistakes; it is no sandbox.
654
661
 
662
+ On Cloudflare a procedure waits for its outside call inside the object's transaction, so the whole environment waits
663
+ with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
664
+ `ctx.transaction` (`references/jobs.md`).
665
+
655
666
  ## Links to your own procedures: `ctx.url`
656
667
 
657
668
  `ctx.url('<endpoint id>', { input?, query? })` builds an absolute URL of one of the application's own procedures, on