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

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 +61 -10
  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 +22 -2
  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 +331 -169
  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 +226 -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
@@ -8,39 +8,48 @@ architecture, and a refusal's allowed form is the one fix that passes. There is
8
8
 
9
9
  The refusals agents meet most, and their fix:
10
10
 
11
- | Rule | Means | Fix |
12
- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
13
- | `literal` | the shell (contract, vocabulary, tables, groups, schemas) holds a computed value or call | literal objects, `z.*` calls and imported literal consts; move logic into `.handle(…)` |
14
- | `contract` | the contract does not compile (a reserved role, an unknown action, a wrong field) | the message names the field |
15
- | `package-replacement` | `package.json` names the app under `@fabrika/*`, or a dependency is `workspace:*` | another name; a registry range such as `^0.0.4` |
16
- | `generated-test-hash` | a generated test is missing, edited or stale | `bunx fabrika db test-scaffold`, and commit what it writes |
17
- | `endpoint-fixture` | an endpoint's input cannot be sampled, a fixture or seed names no endpoint, or a member, invitation or link field no endpoint that reads, cancels or revokes one | a literal in `src/__tests__/endpoint-access.fixtures.ts` (`references/tests.md`) |
18
- | `raw-sql` | a driver's `sql` (imported from `bun`, Kysely, `postgres`) | the handles, or `sql: 'read'` and `ctx.sql` |
19
- | `forbidden-import` | a driver, an S3 client, `jose`, `node:http`, `child_process` | the handles, a file column with `ctx.files`, a connector |
20
- | `forbidden-global` | `Bun.sql`, `Bun.serve`, `Bun.spawn`; `globalThis`, `window`, `self`, `global` or `Bun` in a server module | the handles; state lives in a table, not in a global; `crypto.randomUUID()` for an id |
21
- | `env-read` | `process.env`, `Bun.env` | `defineDeps(build)`, which receives the application's variables |
22
- | `client-identity` | an input field `userId`, `ownerId`, `createdBy`, `tenantId`, `workspaceId` | the access form's `from`, `ctx.principal.id`, or `createdBy` in the policy |
23
- | `type-assertion` | `as T` (other than `as const`), `<T>x` | fix the type; `fromRow` parses a row into a schema's type |
24
- | `sensitive-log` | a log of an error object, a request, headers or the environment | log a short fixed message |
25
- | `migration-name` | a migration not named `YYYYMMDDHHMMSS_slug.sql` (UTC) | `bunx fabrika db new <slug>` |
26
- | `test-only-import` | `@fabrika/app/testing`, `@fabrika/app/react/testing` or `@fabrika/db/testing` outside a test file | import them only from `*.test.ts` or `__tests__/` |
27
- | `spa-server-import` | the SPA loads a server module | the SPA imports `@fabrika/app/client`, the contract, `src/schemas.ts` and `src/shared/` |
28
- | `shared-import` | a module under `src/shared/` loads a slice, `src/db/`, `@fabrika/*` or a builtin | a shared module imports `zod/v4` and other shared modules only |
29
- | `skipped-test` | `.skip`, `.only`, `.todo` | run the test |
30
- | `file-column-migration` | a file column without `REFERENCES fabrika_files (id)` or without an index it leads | both, in a new migration (`references/table-and-migration.md`) |
31
- | `on-conflict-index` | `insert(…, { onConflict: { columns } })` whose columns are no unique index the migrations create | a `UNIQUE` constraint or a `CREATE UNIQUE INDEX` without `WHERE` on exactly those columns |
32
- | `cross-app-fetch` | a `fetch` of an absolute URL under no origin a site declares in `egress` | `egress: ['https://…']` on the site that calls it (`references/endpoint.md`) |
33
- | `url-endpoint` | `ctx.url('<id>')` names no procedure of the contract | the endpoint id `<mount>.<group>.<procedure>` |
11
+ | Rule | Means | Fix |
12
+ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
13
+ | `literal` | the shell (contract, vocabulary, tables, groups, schemas) holds a computed value or call | literal objects, `z.*` calls and imported literal consts; move logic into `.handle(…)` |
14
+ | `contract` | the contract does not compile (a reserved role, an unknown action, a wrong field) | the message names the field |
15
+ | `package-replacement` | `package.json` names the app under `@fabrika/*`, or a dependency is `workspace:*` | another name; a registry range such as `^0.0.4` |
16
+ | `generated-test-hash` | a generated test is missing, edited or stale | `bunx fabrika db test-scaffold`, and commit what it writes |
17
+ | `endpoint-fixture` | an endpoint's input cannot be sampled, a fixture or seed names no endpoint, a member, invitation or link field no endpoint that reads, cancels or revokes one, a file names no file field or a path outside the application, or a refusal is `validation` | a literal in `src/__tests__/endpoint-access.fixtures.ts` (`references/tests.md`) |
18
+ | `raw-sql` | a driver's `sql` (imported from `bun`, Kysely, `postgres`) | the handles, or `sql: 'read'` and `ctx.sql` |
19
+ | `forbidden-import` | a driver, an S3 client, `jose`, `node:http`, `child_process` | the handles, a file column with `ctx.files`, a connector |
20
+ | `forbidden-global` | `Bun.sql`, `Bun.serve`, `Bun.spawn`; `globalThis`, `window`, `self`, `global` or `Bun` in a server module | the handles; state lives in a table, not in a global; `crypto.randomUUID()` for an id |
21
+ | `env-read` | `process.env`, `Bun.env` | `defineDeps(build)`, which receives the application's variables |
22
+ | `client-identity` | an input field `userId`, `ownerId`, `createdBy`, `tenantId`, `workspaceId` | the access form's `from`, `ctx.principal.id`, or `createdBy` in the policy |
23
+ | `type-assertion` | `as T` (other than `as const`), `<T>x` | fix the type; `fromRow` parses a row into a schema's type |
24
+ | `sensitive-log` | a log of an error object, a request, headers or the environment | log a short fixed message |
25
+ | `migration-name` | a migration not named `YYYYMMDDHHMMSS_slug.sql` (UTC) | `bunx fabrika db new <slug>` |
26
+ | `migration-edited` | a migration already on the main branch, edited (even a comment), renamed or deleted | restore the file; put the change in a new migration (`bunx fabrika db new <slug>`) |
27
+ | `test-only-import` | `@fabrika/app/testing`, `@fabrika/app/react/testing`, `@fabrika/db/testing` or `@fabrika/db/testing-sqlite` outside a test file | import them only from `*.test.ts` or `__tests__/` |
28
+ | `spa-server-import` | the SPA loads a server module | the SPA imports `@fabrika/app/client`, the contract, `src/schemas.ts` and `src/shared/` |
29
+ | `shared-import` | a module under `src/shared/` loads a slice, `src/db/`, `@fabrika/*` or a builtin | a shared module imports `zod/v4` and other shared modules only |
30
+ | `tool-import` | a module outside `tools/` loads a developer's tool under `tools/` | move what both need under `src/` (`src/shared/`) and import it from the tool |
31
+ | `skipped-test` | `.skip`, `.only`, `.todo` | run the test |
32
+ | `file-column-migration` | a file column without `REFERENCES fabrika_files (id)` or without an index it leads | both, in a new migration (`references/table-and-migration.md`) |
33
+ | `on-conflict-index` | `insert(…, { onConflict: { columns } })` whose columns are no unique index the migrations create | a `UNIQUE` constraint or a `CREATE UNIQUE INDEX` without `WHERE` on exactly those columns |
34
+ | `cross-app-fetch` | a `fetch` of an absolute URL under no origin a site declares in `egress` | `egress: ['https://…']` on the site that calls it (`references/endpoint.md`) |
35
+ | `url-endpoint` | `ctx.url('<id>')` names no procedure of the contract | the endpoint id `<mount>.<group>.<procedure>` |
36
+ | `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
37
+ | `cloudflare-job-segment` | on Cloudflare, a job whose `limits.timeoutMs` exceeds one 14-minute segment | at most 14 minutes: claim a bounded batch per run, and the next run takes the rest |
38
+ | `cloudflare-current-timestamp` | on Cloudflare, `DEFAULT CURRENT_TIMESTAMP` in a migration: SQLite stores `YYYY-MM-DD HH:MM:SS`, which every read of the table refuses | `DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`, in a new migration |
39
+ | `cloudflare-framework-name` | on Cloudflare, a `fabrika_*` name in a migration, quoted or not | your own tables, and `REFERENCES fabrika_files (id)` for a file column |
40
+ | `migration-refused` | a migration statement Control refuses (a function, an object or a form the platform does not admit) | a new migration that does without it; a key in a SQLite backfill: the UUID expression in `table-and-migration.md` |
41
+ | `backup-schema` | on Cloudflare, a schema the backup cannot copy: a key back into its own table that a `CHECK` reads, or that is `NOT NULL` | a nullable key no `CHECK` names, or no such key; a new migration, before any further one deploys |
34
42
 
35
43
  The hints:
36
44
 
37
- | Hint | Means | Fix |
38
- | ---------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
39
- | `handler-location` | a `.handle(…)` outside a slice's `endpoints.ts` | move the endpoint into `src/<slice>/endpoints.ts` |
40
- | `data-access-location` | `ctx.db` or `ctx.sql` outside `endpoints.ts` and `queries.ts` | pass the handle into a function of the slice's `queries.ts` |
41
- | `logic-data-access` | `logic.ts` reaches data | keep `logic.ts` pure; pass it plain values |
42
- | `cross-slice-queries` | a slice loads another slice's `queries.ts` | move the function, or call that slice's endpoint |
43
- | `sql-undeclared` | `ctx.sql` in a handler whose endpoint declares no `sql` | add `sql: 'read'` (or `'write'`) to that endpoint |
45
+ | Hint | Means | Fix |
46
+ | ---------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
47
+ | `handler-location` | a `.handle(…)` outside a slice's `endpoints.ts` | move the endpoint into `src/<slice>/endpoints.ts` |
48
+ | `data-access-location` | `ctx.db` or `ctx.sql` outside `endpoints.ts` and `queries.ts` | pass the handle into a function of the slice's `queries.ts` |
49
+ | `logic-data-access` | `logic.ts` reaches data | keep `logic.ts` pure; pass it plain values |
50
+ | `cross-slice-queries` | a slice loads another slice's `queries.ts` | move the function, or call that slice's endpoint |
51
+ | `sql-undeclared` | `ctx.sql` in a handler whose endpoint declares no `sql` | add `sql: 'read'` (or `'write'`) to that endpoint |
52
+ | `cloudflare-held-call` | on Cloudflare, a mutation that declares `egress` or `connect` holds the whole environment while it waits | record a row and `ctx.kick('<job>')`; the job makes the call outside `ctx.transaction` |
44
53
 
45
54
  The first run may report only the contract's refusals: the generated-test findings appear once the contract compiles.
46
55
 
@@ -65,6 +74,7 @@ A kit error lands on the line of the mistake, in one or two lines that name the
65
74
  | `'member.label' is possibly 'null'` | a nullable column or output; only `directory: 'labels'` makes it text |
66
75
  | `admin is a role IAM defines itself for every application (reserved: admin)` | another role name |
67
76
  | `Property 'id' does not exist on type 'Ref<…>'` | `ctx.target.value` |
77
+ | `Property 'taskId' does not exist on type '{ … }'` on `input` | `ctx.target.value`, or `ctx.capabilities.<name>.value` |
68
78
  | `Property 'margin' does not exist on type 'Omit<DealsTable, "margin">'` | the column has its own read action, which this capability lacks |
69
79
  | `Type 'Date' is not assignable to type 'string'` on a `date` column | a `YYYY-MM-DD` string |
70
80
  | `Cannot find module '@fabrika/…'` and implicit `any`s everywhere | `bun install` (at the repository root in a monorepo) |
@@ -97,13 +107,16 @@ with its message; throw the three business errors for the application's own refu
97
107
 
98
108
  A 500 answers a fixed message; the server log has one line, `fabrika: <endpoint>: <code>: <reason>: <text>`, with a
99
109
  fixed failure code and, for a framework refusal, its reason and the reason's fixed text, never a value or your error's
100
- message. The codes you meet most:
101
-
102
- | Code | Means |
103
- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
104
- | `query_refused` | the data layer refused a statement or an operation: `undeclared_reach`, `sql_read_only`, `unknown_column`, `read_only`, `sql_outside_transaction` …; the reason's text names the rule |
105
- | `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), or one kept past its request (`ended`, `foreign_work`) |
106
- | `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, or test the handler |
110
+ message. The refusal's own message names the place (`'sqlite_master' at line 2`, the column, the function): for every
111
+ 5xx, `fabrika app dev` prints what was thrown after that line, and a test sees it when it passes a sink to the kit
112
+ (`references/tests.md`). The codes
113
+ you meet most:
114
+
115
+ | Code | Means |
116
+ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
117
+ | `query_refused` | the data layer refused a statement or an operation: `undeclared_reach`, `sql_read_only`, `unknown_column`, `read_only`, `sql_outside_transaction`, `sql_scope`, `sql_name` …; the reason's text names the rule |
118
+ | `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), or one kept past its request (`ended`, `foreign_work`) |
119
+ | `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, `app dev` prints it |
107
120
 
108
121
  With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
109
122
  threw: the error's type, its message, its stack and its `cause` chain. Read the stack there, not in the log. A crash
@@ -76,7 +76,8 @@ task_attachments: {
76
76
  cascade) or clearing a nullable column removes the reference; the framework's sweep deletes a file no column
77
77
  references.
78
78
  - A file column takes only a file reference: an input file (`file('<kind>')`), a `ctx.files.put` of this request, or a
79
- reference this request read from a file column under that table's `read` action. A string id is refused.
79
+ reference this request read from a file column under that table's `read` action (or claimed with its queue row while
80
+ the job declares that action). A string id is refused.
80
81
 
81
82
  ```ts src/attachments/endpoints.ts
82
83
  import { file } from '@fabrika/app/contract'
@@ -209,7 +210,8 @@ a view that maps them.
209
210
  | `put(kind, bytes, { type, name? })` | stores a new file of the kind and answers its reference; it is pending until a column holds it |
210
211
  | `open(ref, { maxBytes? })` | `{ id, name, type, size, bytes }` of a live file, read whole |
211
212
 
212
- `open` takes a reference the site read from a file column under that table's `read` action. It answers 409
213
+ `open` takes a reference the site read from a file column under that table's `read` action, or a queue row a job
214
+ claimed while it also declares that action (`references/jobs.md`). It answers 409
213
215
  `file_not_ready` until the scan called the file clean, 409 `file_rejected` for a rejected one, and 413 for a file over
214
216
  `maxBytes` (the kind's by default), before any byte is read. Pass the size you hold in memory.
215
217
 
@@ -363,7 +365,8 @@ export const erase = app.cron('30 2 * * *', {
363
365
  ## Malware scan
364
366
 
365
367
  `scan: true` on a kind holds every file of it `quarantined` until ClamAV answers clean; on Zerops the platform
366
- installs ClamAV and runs the scan job. A file answer is 409 `file_not_ready` until then and 409 `file_rejected` once
368
+ installs ClamAV and runs the scan job. No scanner runs on Cloudflare: the deploy and the boot refuse a kind with
369
+ `scan: true` there, and so a public procedure with a file field. A file answer is 409 `file_not_ready` until then and 409 `file_rejected` once
367
370
  the file is `rejected`; a list shows each file's `status`, so show it rather than a broken link. In a test, the scan runs with
368
371
  `kit.runJob(FILE_SCAN_JOB)` and a `scanner` passed to `testKit` (`references/tests.md`); the generated tests pass their
369
372
  own seeded files.
@@ -401,7 +404,8 @@ the transaction that deletes the row. The file is never copied; the sweep delete
401
404
  ## Storage
402
405
 
403
406
  On Zerops, declare one `object-storage` service in `fabrika.config.ts`; the platform writes `FABRIKA_APP_STORAGE_*`
404
- from it. Never read those variables, build a storage URL or import an S3 client.
407
+ from it. Never read those variables, build a storage URL or import an S3 client. On Cloudflare the platform binds the
408
+ environment's R2 bucket itself; declare nothing.
405
409
 
406
410
  ```text
407
411
  // in the services of fabrika.config.ts
@@ -4,8 +4,8 @@ Background work is a cron job: `app.cron(schedule, { actions })` with its `.hand
4
4
  `endpoints.ts` of the slice whose data it works on, mounted under `jobs` in the contract. There are no timers, loops,
5
5
  `setInterval` or self-scheduled work, and no `ctx.jobs.enqueue`: work for later is a row that a run picks up, usually
6
6
  from a queue table with `claim` (below). A mutation, a webhook or another job that declares `kicks: ['<job>']` and
7
- calls `ctx.kick('<job>')` starts a run within seconds of its commit (the outbox below); the schedule picks up whatever
8
- that run leaves.
7
+ calls `ctx.kick('<job>')` starts a run within seconds of its commit (the outbox below), and `ctx.kick('<job>', { at })`
8
+ starts one at `at`; the schedule picks up whatever that run leaves.
9
9
 
10
10
  ```ts src/overdue/endpoints.ts
11
11
  import { app } from '../app-kit'
@@ -118,7 +118,7 @@ export const contract = app.contract((c) => ({
118
118
  one, since no zone is a day further ahead.
119
119
  - **Reads run outside the transaction; every write runs inside `ctx.transaction((tx) => …)`**, through `tx.db`, fenced
120
120
  by the attempt's lease. A write outside it is a type error that names `tx.db`.
121
- - An attempt that fails or outlives `limits.timeoutMs` (default 15 minutes, at most a day) is retried up to `retries` times, so every write is
121
+ - An attempt that fails or outlives `limits.timeoutMs` (default 14 minutes, at most a day; at most 14 minutes on Cloudflare) is retried up to `retries` times, so every write is
122
122
  idempotent. **Re-read each row under its lock before you write it:** `tx.db.on(ref).getForUpdate()` inside the
123
123
  transaction, decide again on what it answers with the list's whole filter (`isOverdue`), and write with its
124
124
  `version`. The listed row is already old: someone
@@ -146,9 +146,9 @@ export const contract = app.contract((c) => ({
146
146
  builds an absolute link to one of the application's procedures, for an e-mail.
147
147
  - `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
148
148
  each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
149
- - A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework refusal
150
- with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action`; `references/errors.md`),
151
- or `mail_failed` with the transport's code (`mail_failed: provider_rejected`).
149
+ - A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework failure
150
+ with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action`,
151
+ `framework_fault: url_unbuildable`; `references/errors.md`), or `mail_failed` with the transport's code (`mail_failed: provider_rejected`).
152
152
 
153
153
  ## E-mail: `mailer` and `ctx.mail`
154
154
 
@@ -177,7 +177,14 @@ that says so): it records an outbox row and kicks the job (below). `references/p
177
177
  (RFC 8058), so a mailbox offers one-click unsubscribe. The URL is a public procedure of your own with a signed token
178
178
  (`ctx.url('api.mail.unsubscribe', { query: { t: ctx.tokens.sign('unsubscribe', claims, { days: 400 }) } })`,
179
179
  `references/endpoint.md`). There are no free headers. A transport without the header refuses the message.
180
- - The idempotency key covers the attachments and the unsubscribe URL: a repeated key with other content is refused.
180
+ - `broadcast: true` marks one message of a send to many recipients (a newsletter, an announcement to every student),
181
+ as opposed to mail a recipient's own action triggers (a sign-in link, a confirmation). Providers keep the two apart
182
+ and pause an account whose transactional channel carries broadcast mail, so mark every message of a bulk send. It
183
+ needs `unsubscribe`. A transport without `ctx.mail.capabilities.broadcast` refuses it as `invalid_message`. Under
184
+ `mailer: 'installation'` the capability is true even where the installation's provider sends none; the first
185
+ message then fails `invalid_message`, so stop a bulk send at its first refusal instead of failing every row.
186
+ - The idempotency key covers the attachments, the unsubscribe URL and `broadcast`: a repeated key with other content
187
+ is refused.
181
188
  - `idempotencyKey` is 1 to 200 visible ASCII characters, unique per message in the application environment, and
182
189
  derived from the outbox row (`intake-link-<link id>`), never random. `ctx.mail` puts a prefix of the installation
183
190
  and the environment in front of it, so no other application on the same provider account shares it.
@@ -213,15 +220,32 @@ for (const row of await ctx.db.app('mail.send').outbox.claim({ limit: 50 })) {
213
220
  has come and whose attempts are below `maxAttempts` (10 by default), `for update skip locked`. It adds one attempt
214
221
  and moves `<due>` by the backoff: the job's schedule period (60 s without one), doubled per attempt, at most 30
215
222
  days. Each row answers its columns, its new `version` and `ref`.
223
+ - `where` takes the conditions of a `list` (`references/endpoint.md`), a null test included: `[['result', 'is', null]]`
224
+ claims only the rows without a result.
216
225
  - Claim through the capability you read the table with: `ctx.db.app('<action>').<table>` for an application table,
217
226
  `ctx.db.over(ctx.within('<action>', '<dimension>')).<table>` for a scoped one. The action is the table's `update`
218
227
  action. `claim` runs only in a job and never inside `ctx.transaction`.
228
+ - A claimed row's file column is a reference the job opens (`ctx.files.open`) only when the job also declares the
229
+ table's `read` action. With only the update action it carries the metadata, and `open` refuses it. A column with
230
+ its own read action is in the claim's answer only when that action is the claim's own, and is then readable.
231
+
232
+ ```text
233
+ // uploads: read 'uploads.read', update 'uploads.process', files: { file: 'documents' }
234
+ app.cron('*/5 * * * *', { actions: ['uploads.read', 'uploads.process'] }).handle(async ({ ctx }) => {
235
+ for (const row of await ctx.db.app('uploads.process').uploads.claim({ limit: 5 })) {
236
+ const document = await ctx.files.open(row.file)
237
+ …
238
+ }
239
+ })
240
+ ```
219
241
  - Finish each row in its own transaction through `tx.db.on(row.ref)`: `.update(values, { expectVersion, done: true })`
220
242
  writes and clears `<due>`; `.remove({ expectVersion })` deletes the row (the table's delete action);
221
243
  `.requeue({ at? })` makes it due again at `at` (now by default) with no attempts, for a dead row or a reminder moved
222
244
  later.
223
245
  - A failure or a crash leaves the row as the claim left it, due again after the backoff; nothing retries at once.
224
246
  Attempts count claims, so claim only what the run will reach.
247
+ - A claim that leased rows runs the job again when the same claim would next find one (its `where`, its scope, below
248
+ `maxAttempts`), no sooner than a second later; a claim that took its full `limit` runs it again at once.
225
249
  - A row past `maxAttempts` stays in the table, no longer due, for the application to show or requeue.
226
250
  - One recipe covers an outbox, a per-record reminder (`<due>` is the reminder time) and asynchronous work: a mutation
227
251
  inserts a request row and kicks; the job claims it, renders, puts the result into a file column with
@@ -237,9 +261,17 @@ row, in its own transaction: a public procedure's row (`registrations`), an outb
237
261
  transaction committed, the job runs within seconds, under its own key, and the answer does not wait for it. A thrown
238
262
  handler, a refused answer and a failed commit kick nothing. Kicks coalesce: at most one run is active and one pending,
239
263
  however many calls arrive. A kick carries nothing; the job reads its rows, and its schedule stays the recovery.
264
+ The kick is written in the site's transaction, so a crash right after the commit still runs the job.
240
265
  `kicks` names cron jobs of the contract, as literals (`r.mutation({ …, kicks: ['testMails'] })`); a mutation, a
241
266
  webhook and a job declare it, and the kick edges never form a cycle.
242
267
 
268
+ **A kick for later.** `ctx.kick('<job>', { at })`, with `at` a `Date`, runs the job at that time instead of after the
269
+ commit: a reminder, a retry the application times itself. Kicks of one job in the same second are one; kicks at
270
+ different times stay apart, and a run takes only those already due. The second argument is the time and nothing else;
271
+ what to do stays in the job's rows (`where <due> <= now()`, or a queue table's `<due>`). On Cloudflare the object's
272
+ alarm runs it within seconds of `at`; on Bun the serving process that wrote it runs it at `at`, and another process
273
+ finds it within a minute.
274
+
243
275
  The rules of the job:
244
276
 
245
277
  - **Bounded batches.** Each run takes at most a fixed number of records (`order by received_at, id limit 50`), oldest
@@ -1,7 +1,7 @@
1
1
  # references/table-and-migration.md — the vocabulary, migrations and table policies
2
2
 
3
- The order is fixed: the vocabulary, then the migration, then `fabrika db migrate` and `fabrika db codegen`, then the
4
- table policies, which take the generated `columns`.
3
+ The order is fixed: the vocabulary, then the migration, then `fabrika db migrate` and `fabrika db codegen` (on
4
+ Cloudflare `codegen` only), then the table policies, which take the generated `columns`.
5
5
 
6
6
  ## The vocabulary
7
7
 
@@ -147,7 +147,21 @@ INSERT INTO priorities (code, label, rank) VALUES ('low', 'Low', 1), ('normal',
147
147
  - A column with a fixed set of values is an `ENUM` type, not a `CHECK` on text: the generated tests fill text columns
148
148
  with markers, which a `CHECK` refuses.
149
149
  - Codegen types: `date` is a `YYYY-MM-DD` string; `timestamptz` reads a `Date` and takes a `Date` or a strict ISO 8601 string with `Z` or an offset;
150
- `int8` and `numeric` are strings; an enum is its literal union. JSON, `bytea`, arrays and domains are refused.
150
+ `int8` and `numeric` are strings; an enum is its literal union. `bytea`, arrays and domains are refused.
151
+ - A column of JSON is `jsonb` (`json` is refused: it keeps whitespace and duplicate keys). It reads as `unknown`: parse it
152
+ with a zod schema in the handler, never trust its shape. A write takes a JSON value (plain objects and arrays, strings,
153
+ finite numbers, booleans; a `Date`, a `Map` or a class instance is refused), and `null` is SQL NULL. Type a value you
154
+ write with a `type` alias or a zod-inferred type: an `interface` has no index signature, so it is not a
155
+ `JsonColumnValue`. Postgres reorders an object's keys; compare values, not their `JSON.stringify` text. A `where`,
156
+ `orderBy` or aggregate never names a JSON column: read a path of it with `ctx.sql` (`details ->> 'kind'`), and write
157
+ one there as `${JSON.stringify(value)}`.
158
+ - A generated column (`GENERATED ALWAYS AS (…) STORED`) of any type codegen does not type (a `tsvector` for full-text
159
+ search, a `json`, an array, a range) is left out of the generated types instead: every `fabrika db codegen` run,
160
+ `--verify` too, prints `<table>.<column> (<type>, generated) is left out`, and `schema.generated.ts` has a comment
161
+ where the column would stand. No `ctx.db` handle reads or writes it, a policy cannot name it, and only `ctx.sql`
162
+ reaches it. An identity column and a generated column of a type codegen does type are never left out. A left-out
163
+ column in the primary key, a unique key or a foreign key is refused, and so is a table whose every column would be
164
+ left out.
151
165
  - Plain SQL of the application's own schema only. Refused: another schema (`public.`, `app_…`), any `fabrika_*`
152
166
  object (a file column references `fabrika_files (id)`, `references/files.md`), `GRANT`, roles, `CREATE EXTENSION`, `COPY`,
153
167
  `SET`, transaction control, `SECURITY DEFINER`, a domain, `serial` and sequences (use `GENERATED ALWAYS AS IDENTITY`),
@@ -155,6 +169,36 @@ INSERT INTO priorities (code, label, rank) VALUES ('low', 'Low', 1), ('normal',
155
169
  - Never edit, rename or delete a committed migration; add a new one. Change a schema by expand, switch, contract, and
156
170
  ask before you drop or rename anything.
157
171
 
172
+ ## On Cloudflare: SQLite migrations
173
+
174
+ An application on Cloudflare (its `fabrika.config.ts` imports `defineApp` from `@fabrika/provider-cloudflare`) writes
175
+ its migrations in SQLite. Its Durable Object applies them when it boots, each file once in name order, in a transaction
176
+ of its own, so there is no `fabrika db migrate`; `fabrika db codegen` applies them to an in-memory database and needs
177
+ no URL. The rules above for keys, chains, composite foreign keys, `version` and `created_by` hold unchanged, and the
178
+ database enforces foreign keys.
179
+
180
+ - The declared types codegen reads: `TEXT` (a UUID too), `INTEGER`, `REAL`, `BLOB`; `BOOLEAN`, stored as 0 or 1 and
181
+ read as a boolean; `TIMESTAMP`, stored as UTC ISO text and read as a `Date`; `DATE`, `YYYY-MM-DD` text; `JSONB`,
182
+ stored as JSON text and handled as Postgres's `jsonb` above (`JSON` is refused). Any other declared type is refused.
183
+ A generated column of another declared type (`JSON`) is left out as on Postgres; one with no declared type is
184
+ refused, so declare it. A `STRICT` table admits only `INTEGER`, `REAL`, `TEXT` and `BLOB`, so a table with a
185
+ `BOOLEAN`, `TIMESTAMP`, `DATE` or `JSONB` column is not `STRICT`. `ctx.sql` reads a `JSONB` column as its text, or
186
+ as a number when the value is one; parse the text with `JSON.parse`.
187
+ - SQLite has no `ENUM`: a column with a fixed set of values is `TEXT` with `CHECK (<column> IN ('a', 'b'))`. The
188
+ generated tests write its first value.
189
+ - No transaction control (`BEGIN`, `COMMIT`, `SAVEPOINT`) and no Postgres syntax (`timestamptz`, `::` casts,
190
+ `GENERATED ALWAYS AS IDENTITY`, `CREATE TYPE`).
191
+ - SQLite has no `gen_random_uuid()`. A backfill that inserts rows gives each one a key with this expression, a UUID v4
192
+ that `z.uuid()` accepts (`hex(randomblob(16))` alone is not one). It is random, not time-ordered like the UUIDv7 an
193
+ insert of the data layer stamps, so nothing may depend on the order of these keys.
194
+
195
+ ```sql
196
+ INSERT INTO deal_tags (id, deal_id, tag)
197
+ SELECT lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)), 2) || '-'
198
+ || substr('89ab', 1 + (random() & 3), 1) || substr(hex(randomblob(2)), 2) || '-' || hex(randomblob(6))), id, label
199
+ FROM deals WHERE label IS NOT NULL;
200
+ ```
201
+
158
202
  ## Database code is a declared deviation
159
203
 
160
204
  A function, trigger, view, rule, policy or `DO` block in a migration is allowed. The migration file declares it, and
@@ -10,9 +10,11 @@ longer writes. Commit them; never edit, format or import them (`generated-test-h
10
10
  every `on` and `over` endpoint, and every `in` endpoint that declares `sql`, answers nothing of another scope; a
11
11
  caller with only an endpoint's write action, plus what IAM requires of it (below), reaches its own object (200). An
12
12
  `app` or `creates` endpoint refuses a holder of its action in one scope only (403) and answers a global holder. An
13
- endpoint of several `capabilities` adds a denied case per capability. A public procedure answers anyone without a
14
- credential, or, behind a challenge, refuses a caller without a solved one. A file input is sent as a generated file
15
- of its kind; a `GET` procedure's input goes in its URL.
13
+ endpoint of several `capabilities` adds a denied case per capability (none for an `over` one whose action another one
14
+ needs on its dimension, a container of it or a dimension inside it, which gets a `// Not checked:` line instead). A
15
+ public procedure answers anyone without a credential, or, behind a challenge, refuses a caller without a solved one.
16
+ A file input is sent as a generated file of its kind, or as the file the fixtures name (`files`, below); a `GET`
17
+ procedure's input goes in its URL.
16
18
  - Their kit stands in for IAM, as `testKit` does (below): it creates a scope, assigns or invites a member and issues a
17
19
  link under IAM's rules for the caller's grants. A repeated invitation answers the open one, `resend` restarts its
18
20
  7 days, and an organization's address is refused for an external role (`internal_mailbox`). So the caller of an endpoint with the dimension's `members.manage`
@@ -59,15 +61,50 @@ export const members = { 'api.tasks.assign': ['assignee'] }
59
61
  table of the table that owns it, or a table it contains; the checker refuses a row further down
60
62
  (`endpoint-fixture`). Without it they send a sample, the handler
61
63
  finds no row (404), and the case fails.
64
+ - `appRows['<endpoint id>']` gives the rows of application tables (`scope: { app }`) that the endpoint's handler reads
65
+ for the caller's own scope, by table, with the columns they need: `export const appRows = { 'portal.guide': { guides:
66
+ { active: true } } }`. Each of its leak and own-object cases seeds one row of each before it asks and removes them
67
+ once it is over, with every row that refers to them (a download the handler logged), so a handler that reads the
68
+ newest guide answers 200 instead of 404, and no other endpoint's case finds the row. A foreign key from one given row
69
+ to another holds that row's key. A text column may be given; the key, the version, the creator and a file column may
70
+ not (a file column holds a live, scanned file). Only application tables, and only for an endpoint with a leak or an
71
+ own-object case: the checker refuses a table in a scope, which `rows` and `seeds` address (`endpoint-fixture`).
72
+ - `files['<endpoint id>']` names, by file field, a file of the repository that every case of the endpoint sends there
73
+ instead of the generated one, a path from the application's root:
74
+ `export const files = { 'api.skills.publish': { package: 'src/__tests__/fixtures/skill.zip' } }`. Give one when the
75
+ handler inspects the content (a package it unpacks, a document it parses) and answers 400 to the generated file, which
76
+ has only the leading bytes of its type. Commit the file; keep it small and free of real data. The kit sends it with the
77
+ first type of the field's kind its bytes are, and a file it cannot read, or of none of those types, fails the case. The
78
+ checker refuses a field that holds no file and a path that leaves the application, starts with `.` or has characters
79
+ other than letters, digits, `_`, `-`, `.` and `/` (`endpoint-fixture`).
80
+ - `pins['<endpoint id>']` gives text columns of the row the endpoint addresses (the row of the table that owns its
81
+ dimension) a known value instead of the seed's marker: `export const pins = { 'api.skills.publish': { slug:
82
+ 'published-skill' } }`, when the handler ties the column to the input or to the file in `files` (a package whose
83
+ `SKILL.md` names the skill's slug). The own scope's row holds the value, the other scope's `<value>-other`, which a
84
+ leak case still looks for in the own scope's answer. A pin of a column that places the row, or of no text column,
85
+ fails the case; the checker refuses one of an endpoint without an addressed row (`endpoint-fixture`).
86
+ - `refusals['<endpoint id>']` lists the error types of the 400s the endpoint's handler answers with when its rule ties
87
+ the row to the input and the scope is the other one: `export const refusals = { 'api.skills.publish':
88
+ ['skill_frontmatter'] }`, beside the pin above. A leak case asks from the other scope first, whose pinned value the
89
+ package does not name; that request may answer one of them. The own case passes on 200 or one of them, and the
90
+ denial cases still expect 404 or 403. The answer a leak case checks, the own scope's, still fails on it, because an
91
+ answer that holds nothing proves no isolation: pin the row and give the file so that the own scope succeeds. Any
92
+ other 400 fails the case, and the checker refuses `validation`, an input the schema refuses (`endpoint-fixture`).
62
93
  - The endpoint id is `<mount>.<group>.<endpoint>` (`api.tasks.close`).
63
94
  - The seed of the tests fills every text column with a marker and every other required column with a sample of its
64
- type: an enum's first label, `1`, `false`, today. A column with a `DEFAULT` keeps it (`status` is `open`). A column
65
- a `CHECK` names gets the first value of an `IN (…)` list, or `null` where it is nullable. A foreign key outside
66
- the containment chain is `null` where it is nullable, and otherwise references an existing or a seeded row of a
67
- reference or application table. What the seed cannot satisfy (another `CHECK` on a required text column, a required
68
- key to a dimension or child table outside the chain) fails the test with a `SeedLimitError` that names the
69
- constraint: a limit of the generator, not a bug of the handler. Keep the column as the domain needs it, and ask the
70
- human when the limit blocks the tests.
95
+ type: an enum's first label, `1`, `false`, today. A number column that a `UNIQUE` index or the primary key covers
96
+ gets the next number above the largest among the rows that share the index's other columns with it instead (`1`
97
+ under a fresh parent, `2` for the insert case beside the seeded row; the whole column for a one-column index), so
98
+ the row collides with no row of the table. A column with a `DEFAULT` keeps it (`status` is `open`). A column a
99
+ `CHECK` names gets the first value of an `IN (…)` list, or `null` where it is nullable. A foreign key outside the
100
+ containment chain is `null` where it is nullable, and otherwise references an existing or a seeded row of a
101
+ reference or application table. What the seed cannot satisfy (another `CHECK` on a required text column, a unique
102
+ number column whose type holds no larger number, a `UNIQUE` index whose sampled values another row holds, such as a
103
+ date, an enum or a boolean unique on its own, a required key to a dimension or child table outside the chain) fails
104
+ the test with a `SeedLimitError` that names the constraint: a limit of the generator, not a bug of the handler. The
105
+ numbering reads only a `UNIQUE` index of plain columns with no `WHERE`. A collision the seed does not write itself (a
106
+ non-number column unique within the parent, which the insert case's row shares with the seeded one) answers 500 in
107
+ the insert case. Keep the column as the domain needs it, and ask the human when the limit blocks the tests.
71
108
  - A generated case's input is a sample of the schema: no optional field, `null` for a nullable one, an enum's first
72
109
  value, the shortest string its bounds admit (`'x'`), the smallest number, `false`, a fixed value for a format
73
110
  (`uuid`, `email`, `iso.date`). When that input meets a precondition (`close` of an `open` task is 409), seed the
@@ -196,6 +233,9 @@ if (postgres !== null) {
196
233
  `<label> skipped: set FABRIKA_TEST_POSTGRES_URL to run the Postgres-backed tests`, and the file registers no test.
197
234
  A skip proves nothing. To confirm a file ran, run it alone (`bun test --isolate src/tasks`) and check that the pass
198
235
  count is its number of tests, or set `FABRIKA_TEST_POSTGRES_REQUIRED=1`: a missing URL then fails the file.
236
+ - On Cloudflare import `testDatabase` from `@fabrika/db/testing-sqlite` instead, with the same options: it migrates a
237
+ fresh in-memory SQLite database as the Durable Object does, needs no URL and never answers `null`. The generated tests
238
+ already use it.
199
239
  - `statusOf(call)` answers 200 when the call resolves and the status of the application's refusal otherwise; any other
200
240
  failure (no answer, a bug in the test) is rethrown. Import it beside `testKit`; do not write your own.
201
241
  - `kit.testCaller(grants, { kind })` makes a caller: a grant is a role or an action, in one scope or global. A
@@ -281,6 +321,10 @@ if (postgres !== null) {
281
321
  - `testKit(app, { membership })` replaces the stand-in with your own `IamMembershipRpc`; that kit accepts no
282
322
  invitation. `@fabrika/app/testing` exports the types of the options: `IamMembershipRpc` (`membership`),
283
323
  `ChallengeFetch` (`challengeFetch`) and `FileScanner` (`scanner`). Import them from there, beside `testKit`.
324
+ - A 5xx or a failed `kit.runJob` names only its code and reason. To see what was thrown (your handler's error, or a
325
+ refusal's own message: a refused `ctx.sql` names its line, a refused column its name), pass a sink while you debug:
326
+ `testKit(app, { database: postgres.database, revealHandlerErrors: (where, error) => console.error(where, error) })`
327
+ (`HandlerErrorSink`). It is off unless passed.
284
328
  - `kit.testCaller(grants, { disabled: true })` is a person an operator disabled: the directory lists and finds them
285
329
  with `disabled: true`, so an assignment of them answers your handler's 400, and their own requests are refused (401 for
286
330
  a session, 403 for a key).
@@ -290,6 +334,13 @@ if (postgres !== null) {
290
334
  - A mutation that kicks (`kicks`, `ctx.kick`) starts its job in the background of the call. `kit.drain()` waits for
291
335
  those runs, and `kit.runJob` first waits for them; every generated access case drains before it answers. The kicked
292
336
  run may start at once, so arm a fault before the call, never between the call and the run.
337
+ - `await kit.runDueJobs({ within: 3 * 3600000 })` runs every job with a wake due now or within `within` milliseconds
338
+ (0 by default) once, as the Cloudflare object's alarm runs it: a cron job's next fire, a kick, a failed run's retry.
339
+ It answers `[{ job, result }]` for the runs it started, and first waits for the kicked runs. Without it the kit fires
340
+ no wake: a cron job runs only through `runJob` or `runDueJobs`. Only the wakes move, never the clock: a handler's
341
+ `new Date()` and a queue row's due time stay real, so a row due later is not claimed early. A second call does not run
342
+ a cron fire the first one ran early. A failed run of a job with `retries` is due again after its backoff, at most a
343
+ second for the first retry, so `runDueJobs({ within: 2000 })` runs it. It needs the application's data layer.
293
344
  - `kit.mail` is the stand-in for every job's mail transport (`MemoryEmailSender` of `@fabrika/app/testing`), so a test
294
345
  needs no mail variable. `kit.mail.accepted` is what reached the inbox, once per key, and `kit.mail.handoffs` every
295
346
  send with its `answer`. `refuse(code?)`, `unavailable()`, `unreachable()`, `loseAnswers(n)` and `during(hook)`
@@ -89,7 +89,7 @@ export const integrations = app.group({ callers: ['human'] }, (r) => ({
89
89
  that binds it takes an `app` capability: `access: { action, app: true }`, `binds`, and
90
90
  `ctx.webhooks('<webhook>').bind(ctx.app, account)`.
91
91
  - `limits: { maxBytes?, timeoutMs? }`: the body is 1 MiB by default and at most 48 MiB; the handler runs 10 s by
92
- default, at most 60 s. A webhook may declare `kicks`, `signs`, `egress`, `sql` and `unscoped`, and `ctx.files.put`
92
+ default, at most 60 s (25 s on Cloudflare). A webhook may declare `kicks`, `signs`, `egress`, `sql` and `unscoped`, and `ctx.files.put`
93
93
  stores a file a provider sends (an inbound e-mail's attachment) for a file column: raise `limits.maxBytes` to the
94
94
  mail you accept.
95
95
  - Not covered: a provider that validates its URL with a `GET`, or that needs a custom answer body.