@fabrika/app 0.9.0-cloudflare.1 → 0.9.0-cloudflare.3

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 (72) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +21 -17
  3. package/skill/references/app-setup.md +42 -11
  4. package/skill/references/endpoint.md +29 -22
  5. package/skill/references/errors.md +32 -31
  6. package/skill/references/jobs.md +22 -3
  7. package/skill/references/tests.md +29 -1
  8. package/src/build.ts +6 -1
  9. package/src/bun.ts +168 -5
  10. package/src/cloudflare/application.ts +546 -76
  11. package/src/cloudflare/bindings.ts +26 -5
  12. package/src/cloudflare/export.ts +621 -0
  13. package/src/cloudflare/import.ts +1097 -0
  14. package/src/cloudflare/maintenance.ts +518 -0
  15. package/src/cloudflare/names.ts +6 -0
  16. package/src/cloudflare/ops.ts +147 -18
  17. package/src/cloudflare/restore.ts +167 -0
  18. package/src/cloudflare/tracker.ts +192 -0
  19. package/src/cloudflare.ts +3 -2
  20. package/src/contract/artifact-schema.ts +13 -2
  21. package/src/contract/build.ts +38 -11
  22. package/src/contract/context.ts +26 -9
  23. package/src/contract/defaults.ts +22 -2
  24. package/src/contract/define.ts +1 -1
  25. package/src/contract/group.ts +10 -1
  26. package/src/contract/kit.ts +2 -1
  27. package/src/disk-assets.ts +8 -3
  28. package/src/files/kinds.ts +54 -24
  29. package/src/implement/anonymous.ts +1 -10
  30. package/src/implement/boot.ts +30 -12
  31. package/src/implement/capability.ts +3 -0
  32. package/src/implement/dispatch.ts +175 -37
  33. package/src/implement/egress.ts +367 -8
  34. package/src/implement/invocation.ts +60 -19
  35. package/src/implement/workload.ts +18 -3
  36. package/src/jobs/runner.ts +646 -98
  37. package/src/spa-fallback.ts +12 -0
  38. package/src/testing/endpoint-access.ts +135 -23
  39. package/src/testing/isolation.ts +8 -1
  40. package/src/testing/kit.ts +60 -0
  41. package/types/src/build.d.ts +1 -1
  42. package/types/src/bun.d.ts +34 -1
  43. package/types/src/cloudflare/application.d.ts +36 -5
  44. package/types/src/cloudflare/bindings.d.ts +6 -0
  45. package/types/src/cloudflare/export.d.ts +16 -0
  46. package/types/src/cloudflare/import.d.ts +58 -0
  47. package/types/src/cloudflare/maintenance.d.ts +117 -0
  48. package/types/src/cloudflare/names.d.ts +5 -0
  49. package/types/src/cloudflare/ops.d.ts +39 -4
  50. package/types/src/cloudflare/restore.d.ts +9 -0
  51. package/types/src/cloudflare/tracker.d.ts +29 -0
  52. package/types/src/cloudflare.d.ts +2 -1
  53. package/types/src/contract/artifact-schema.d.ts +2 -0
  54. package/types/src/contract/context.d.ts +24 -9
  55. package/types/src/contract/defaults.d.ts +19 -1
  56. package/types/src/contract/define.d.ts +1 -1
  57. package/types/src/contract/group.d.ts +9 -1
  58. package/types/src/contract/kit.d.ts +2 -2
  59. package/types/src/disk-assets.d.ts +4 -1
  60. package/types/src/files/kinds.d.ts +17 -6
  61. package/types/src/implement/anonymous.d.ts +0 -4
  62. package/types/src/implement/boot.d.ts +17 -0
  63. package/types/src/implement/capability.d.ts +2 -0
  64. package/types/src/implement/dispatch.d.ts +33 -1
  65. package/types/src/implement/egress.d.ts +36 -1
  66. package/types/src/implement/invocation.d.ts +20 -10
  67. package/types/src/implement/workload.d.ts +5 -0
  68. package/types/src/jobs/runner.d.ts +63 -2
  69. package/types/src/spa-fallback.d.ts +2 -0
  70. package/types/src/testing/endpoint-access.d.ts +25 -1
  71. package/types/src/testing/isolation.d.ts +1 -1
  72. package/types/src/testing/kit.d.ts +16 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/app",
3
- "version": "0.9.0-cloudflare.1",
3
+ "version": "0.9.0-cloudflare.3",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -109,14 +109,14 @@
109
109
  "test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
110
110
  },
111
111
  "dependencies": {
112
- "@fabrika/auth": "0.9.0-cloudflare.1",
113
- "@fabrika/auth-core": "0.9.0-cloudflare.1",
114
- "@fabrika/db": "0.9.0-cloudflare.1",
115
- "@fabrika/email": "0.9.0-cloudflare.1",
116
- "@fabrika/jwks": "0.9.0-cloudflare.1",
117
- "@fabrika/platform": "0.9.0-cloudflare.1",
118
- "@fabrika/platform-node": "0.9.0-cloudflare.1",
119
- "@fabrika/proxy-core": "0.9.0-cloudflare.1",
112
+ "@fabrika/auth": "0.9.0-cloudflare.3",
113
+ "@fabrika/auth-core": "0.9.0-cloudflare.3",
114
+ "@fabrika/db": "0.9.0-cloudflare.3",
115
+ "@fabrika/email": "0.9.0-cloudflare.3",
116
+ "@fabrika/jwks": "0.9.0-cloudflare.3",
117
+ "@fabrika/platform": "0.9.0-cloudflare.3",
118
+ "@fabrika/platform-node": "0.9.0-cloudflare.3",
119
+ "@fabrika/proxy-core": "0.9.0-cloudflare.3",
120
120
  "altcha-lib": "2.6.0",
121
121
  "jose": "^5.9.0"
122
122
  },
package/skill/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: fabrika-app
3
- version: 0.9.0-cloudflare.1
3
+ version: 0.9.0-cloudflare.3
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
@@ -231,16 +231,18 @@ the access check. `references/spa.md` shows the stack.
231
231
  | e-mail (a cron job only) | `mailer: 'installation'` | `ctx.mail.send` |
232
232
  | a file from a public procedure | `file('<kind>')` input, `admission` with `bytesPerHour` | a reference the handler writes into a file column |
233
233
  | an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to exactly those origins |
234
+ | any public website (a job) | `egress: 'public'` | `fetch` to public hosts, never the installation |
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
 
@@ -295,12 +297,15 @@ bunx tsc --noEmit # once, at the end
295
297
  bunx fabrika-check . # once, after tsc; refusals fail; hints print below them
296
298
  ```
297
299
 
298
- **On Cloudflare** (`fabrika.config.ts` imports `defineApp` from `@fabrika/provider-cloudflare`) the application runs in
299
- one Durable Object over SQLite. Its `db/migrations/*.sql` are SQLite (`references/table-and-migration.md`), and the
300
+ **On Cloudflare** (`fabrika.config.ts` imports `defineApp` from `@fabrika/provider-cloudflare`, as
301
+ `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
300
302
  object applies them when it boots, so there is no `migrate` and no command needs a database URL or `FABRIKA_APP_ID`.
301
303
  The tests run on `@fabrika/db/testing-sqlite` (`references/tests.md`), in memory, and never skip. A handler holds the
302
- object's transaction, so its `limits.timeoutMs` is at most 25 s. No `sql` (`ctx.sql`) and no `scan: true`: the
303
- checker, the deploy and the boot refuse both.
304
+ object's transaction, so its `limits.timeoutMs` is at most 25 s. A job's is at most 14 minutes, its default: longer
305
+ work claims a bounded batch per run, and the next run takes the rest (`references/jobs.md`). `ctx.sql` is SQLite there
306
+ (`references/endpoint.md`). No `scan: true`: the checker, the deploy and the boot refuse it. A migration names no
307
+ `fabrika_*` table but `REFERENCES fabrika_files (id)`. The deploy serves each SPA mount's
308
+ built `dir` itself; declare no `assets` on the Worker (`references/app-setup.md`).
304
309
 
305
310
  The object runs one transaction at a time, so every `await` in a handler that may write holds the whole environment:
306
311
  IAM, R2, a `fetch`, a `ctx.connect` call, a binding. One 2 s call caps the environment at half a request a second. A
@@ -320,9 +325,8 @@ bun test --isolate # no database URL; t
320
325
 
321
326
  A generated file changes only through its command (`codegen`, `test-scaffold`); running it is the loop, not an edit.
322
327
  Format and lint only the files you wrote, with the repository's own tools: in the fabrika-platform repository
323
- `bunx dprint fmt <files>` and `bunx biome lint <files>`, never `biome check` (its formatter fights dprint), and never a
324
- generated file. An application outside that repository has neither configuration: use the formatter its own
325
- 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
328
+ `bunx dprint fmt <files>` and `bunx oxlint <files>`, and never a generated file. An application outside that
329
+ 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
326
330
  change an uncommitted migration, migrate into a fresh schema with another `FABRIKA_APP_ID`. Read a refusal's
327
331
  "allowed form" and use it; fix hints too. `references/errors.md` explains the findings and the type errors.
328
332
 
@@ -350,9 +354,9 @@ e-mails them, a link holder's files, HR's review with its history.
350
354
  ## Not built yet
351
355
 
352
356
  - On Cloudflare, where the application runs in one Durable Object over its SQLite and its `db/migrations/*.sql` are
353
- SQLite, `sql` (`ctx.sql`) and a file kind with `scan: true` are refused. Everything else on the road runs there.
354
- - 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
355
- carries nothing, and the job finds its work in a queue table with `claim`. A list write is off the road (`sql`).
357
+ SQLite, a file kind with `scan: true` is refused. Everything else on the road runs there.
358
+ - 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
359
+ 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`).
356
360
  - A read across tables (a join, a filter over a related table, an aggregate over several) is off the road (`sql`).
357
361
  - An MCP workspace has no shell, so `codegen` and `test-scaffold` cannot run there. Tell the human; never write a
358
362
  generated file by hand.
@@ -19,20 +19,20 @@ the SPA is added with it.
19
19
  "test": "bun test --isolate"
20
20
  },
21
21
  "dependencies": {
22
- "@fabrika/app": "0.9.0-cloudflare.1",
23
- "@fabrika/db": "0.9.0-cloudflare.1",
24
- "@fabrika/provider-zerops": "0.9.0-cloudflare.1",
25
- "@fabrika/proxy-core": "0.9.0-cloudflare.1",
26
- "@fabrika/ui": "0.9.0-cloudflare.1",
22
+ "@fabrika/app": "0.9.0-cloudflare.3",
23
+ "@fabrika/db": "0.9.0-cloudflare.3",
24
+ "@fabrika/provider-zerops": "0.9.0-cloudflare.3",
25
+ "@fabrika/proxy-core": "0.9.0-cloudflare.3",
26
+ "@fabrika/ui": "0.9.0-cloudflare.3",
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-cloudflare.1",
34
- "@fabrika/cli": "0.9.0-cloudflare.1",
35
- "@fabrika/platform": "0.9.0-cloudflare.1",
33
+ "@fabrika/check": "0.9.0-cloudflare.3",
34
+ "@fabrika/cli": "0.9.0-cloudflare.3",
35
+ "@fabrika/platform": "0.9.0-cloudflare.3",
36
36
  "@happy-dom/global-registrator": "^20.11.2",
37
37
  "@types/bun": "^1.4.3",
38
38
  "@types/react": "^19.0.0",
@@ -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.
@@ -406,7 +406,7 @@ export const workloadRows = (
406
406
  count(*) filter (where t.status <> 'done')::int as open,
407
407
  count(*) filter (where t.status <> 'done' and t.due_on < current_date)::int as overdue
408
408
  from tasks t
409
- where ${sql.scope(org, 'tasks', 't')}
409
+ where ${sql.scope(org, 'tasks', { alias: 't' })}
410
410
  and (${status}::text is null or t.status::text = ${status})
411
411
  group by t.assignee
412
412
  order by t.assignee`
@@ -421,7 +421,7 @@ export const workloadRows = (
421
421
  ## Raw SQL: `sql: 'read'`
422
422
 
423
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. It runs on Postgres only: on Cloudflare a site that declares `sql` is refused.
424
+ `ctx.sql` exists only there. It runs on Postgres and, on Cloudflare, on SQLite (the rules of each are below).
425
425
 
426
426
  ```ts src/reports/endpoints.ts
427
427
  import { attachment } from '@fabrika/app/contract'
@@ -475,7 +475,7 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
475
475
  const rows = await ctx.sql(TaskExportRow)`
476
476
  select t.title, t.status, t.assignee, t.due_on::text as due_on
477
477
  from tasks t
478
- where ${ctx.sql.scope(ctx.target, 'tasks', 't')}
478
+ where ${ctx.sql.scope(ctx.target, 'tasks', { alias: 't' })}
479
479
  order by t.title
480
480
  limit 10000`
481
481
  await ctx.db.target.project_exports.insert({ row_count: rows.length })
@@ -487,7 +487,7 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
487
487
  - Every `${…}` of a value is a bound parameter, never SQL text. The one exception is `${ctx.sql.scope(…)}`: it is SQL
488
488
  (the predicate) around its own bound values, and it may have no value at all (`(true)`, `(false)`). Put no
489
489
  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>')}`.**
490
+ - **Scope every scoped table the statement reads with `${ctx.sql.scope(capability, '<table>', { alias: '<alias>' })}`.**
491
491
  `ctx.sql` has no scope predicate of its own. The fragment is the capability's whole predicate on that table: for a
492
492
  `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
493
  values, each container grant on its own column, every row for a global grant and none for an empty one. The
@@ -495,29 +495,31 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
495
495
  `Within` it minted to `tx.sql.scope`. A table the capability does not reach is a type error at the table name. A
496
496
  reference table is shared by every scope and needs no fragment, and no statement writes it. An application table
497
497
  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.
498
+ - **A fragment states what it scopes.** `use` is `'read'` by default; the table an `update` or `delete` writes takes
499
+ `{ use: 'update' }` or `{ use: 'delete' }`, which needs the table's own update or delete action
500
+ (`ctx.within('tasks.write', 'project')` for `update tasks`) on a `'write'` site, so a read action never scopes a
501
+ write. A column's own write action (`columns: { assignee: { write: 'tasks.assign' } }`) is enough for `use: 'update'`
502
+ too; set only the columns it writes. `insert … on conflict do update … where ${…}` scopes the inserted table with
503
+ `use: 'update'`. Each block takes its own fragment: a CTE that updates and a statement that deletes take one
504
+ capability each, and another occurrence of the written table (a subquery, `from tasks other`) reads under its own
505
+ alias. A refused fragment fails the call before anything is sent.
506
+ - **A fragment is a conjunct.** Put it alone, joined by AND, at the top level of a WHERE or JOIN … ON clause whose top
507
+ level holds no OR: `where (<the whole filter>) and ${…}`, `join projects p on p.id = t.project_id and ${…}`. The tag
508
+ does not read where it stands, which relation it filters or which columns a `set` assigns: the approver does, and a
509
+ fragment under an `or` widens the statement to every row. Never scope by hand with `ctx.target.value` alone: it drops
510
+ the chain. The generated tests check that an `in` endpoint with `sql` leaks nothing of another scope.
512
511
  - Rows are parsed like `fromRow` (snake_case to camelCase), then by the schema. Postgres sends `bigint` and `numeric`
513
512
  as text: cast a count (`count(*)::int`), and a sum to the type its output declares (`::int` for an integer sum that
514
513
  fits, `::float8` for a fractional one), or keep it a string. A sum over no rows is `null`: `coalesce(sum(…), 0)`.
515
514
  - An optional filter is `(${value}::text is null or <column> = ${value})`.
516
515
  - 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.
516
+ job or a webhook). Refused before anything is sent: DDL, `SET`, `COPY`, transaction control, and any `fabrika_*`
517
+ 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_*`
518
+ name, `PRAGMA`, `ATTACH`, and a parameter you write yourself (`?`, `:x`, `@x`, `$x`): interpolate every value.
519
+ - On SQLite write SQLite: `count(*)` is already an integer, there is no `::` cast (`cast(x as text)`), and a list value
520
+ binds as JSON (`t.status in (select value from json_each(${list}))`).
521
+ - A query runs in a read-only transaction; a mutation's `ctx.sql` runs in the same transaction as its handles. A
522
+ `'read'` statement writes nothing, even in a mutation: one that tries fails the call.
521
523
 
522
524
  ## A file download: `attachment`
523
525
 
@@ -656,6 +658,11 @@ On Cloudflare a procedure waits for its outside call inside the object's transac
656
658
  with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
657
659
  `ctx.transaction` (`references/jobs.md`).
658
660
 
661
+ A cron job that calls hosts nobody knows when the contract is written (the websites its operators enter: a crawler, an
662
+ auditor, a link checker) declares `egress: 'public'` instead of a list (`references/jobs.md`). Only a cron job may: a
663
+ procedure, a mutation and a webhook name their origins. Never keep `fetch` from before boot or open sockets to get past
664
+ the list; that is hidden reach.
665
+
659
666
  ## Links to your own procedures: `ctx.url`
660
667
 
661
668
  `ctx.url('<endpoint id>', { input?, query? })` builds an absolute URL of one of the application's own procedures, on
@@ -8,32 +8,33 @@ 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`, `@fabrika/db/testing` or `@fabrika/db/testing-sqlite` 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>` |
34
- | `cloudflare-sql` | on Cloudflare, a site that declares `sql` | the handles (`ctx.db`), without `sql` |
35
- | `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
36
- | `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 |
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
+ | `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__/` |
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`, or one a job's `egress: 'public'` refuses (an IP address, `localhost`) | `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>` |
34
+ | `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
35
+ | `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 |
36
+ | `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 |
37
+ | `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 |
37
38
 
38
39
  The hints:
39
40
 
@@ -103,11 +104,11 @@ A 500 answers a fixed message; the server log has one line, `fabrika: <endpoint>
103
104
  fixed failure code and, for a framework refusal, its reason and the reason's fixed text, never a value or your error's
104
105
  message. The codes you meet most:
105
106
 
106
- | Code | Means |
107
- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
108
- | `query_refused` | the data layer refused a statement or an operation: `undeclared_reach`, `sql_read_only`, `unknown_column`, `read_only`, `sql_outside_transaction`, `sql_dialect` (`ctx.sql` on SQLite, Cloudflare) …; the reason's text names the rule |
109
- | `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`) |
110
- | `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, or test the handler |
107
+ | Code | Means |
108
+ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
109
+ | `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 |
110
+ | `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), one kept past its request (`ended`, `foreign_work`), or a `fetch` its `egress` refuses (`undeclared_egress`, `refused_egress`, `oversized_egress`) |
111
+ | `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, or test the handler |
111
112
 
112
113
  With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
113
114
  threw: the error's type, its message, its stack and its `cause` chain. Read the stack there, not in the log. A crash
@@ -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
@@ -144,6 +144,15 @@ export const contract = app.contract((c) => ({
144
144
  - A job may also declare `kicks` (another job; the edges never form a cycle), `signs` (`ctx.tokens.sign`),
145
145
  `egress` (the HTTPS origins its `fetch` calls) and `issues` (`references/endpoint.md`). `ctx.url('<endpoint id>', …)`
146
146
  builds an absolute link to one of the application's procedures, for an e-mail.
147
+ - A job that calls the websites its operators enter (a crawler, an auditor) declares `egress: 'public'`:
148
+ `app.cron('*/5 * * * *', { actions: ['sites.read'], egress: 'public' })`. Its `fetch` reaches any public host over
149
+ HTTPS or HTTP on the default port. It is refused (`capability_refused: refused_egress`) for an IP address, a name of
150
+ one label (`localhost`, an internal service), a name under `.local`, `.internal`, `.workers.dev`, `.zerops.app` and similar, a port,
151
+ the installation's own hosts (IAM, Control, Operations, every application's domain) and, on Bun (Zerops), a name
152
+ that resolves to a private address. Every redirect is checked again: `redirect: 'manual'` gets the redirect, the default
153
+ follows at most 10. A request has 60 s, a response body at most 16 MiB (`oversized_egress`); pass `ctx.signal`, or
154
+ `AbortSignal.any([ctx.signal, AbortSignal.timeout(8_000)])` for a shorter bound per page. The approver reviews it
155
+ closely, as reach to anywhere public. Keep the sites operators enter in a table the job reads.
147
156
  - `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
148
157
  each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
149
158
  - A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework refusal
@@ -229,6 +238,8 @@ for (const row of await ctx.db.app('mail.send').outbox.claim({ limit: 50 })) {
229
238
  later.
230
239
  - A failure or a crash leaves the row as the claim left it, due again after the backoff; nothing retries at once.
231
240
  Attempts count claims, so claim only what the run will reach.
241
+ - A claim that leased rows runs the job again when the same claim would next find one (its `where`, its scope, below
242
+ `maxAttempts`), no sooner than a second later; a claim that took its full `limit` runs it again at once.
232
243
  - A row past `maxAttempts` stays in the table, no longer due, for the application to show or requeue.
233
244
  - One recipe covers an outbox, a per-record reminder (`<due>` is the reminder time) and asynchronous work: a mutation
234
245
  inserts a request row and kicks; the job claims it, renders, puts the result into a file column with
@@ -244,9 +255,17 @@ row, in its own transaction: a public procedure's row (`registrations`), an outb
244
255
  transaction committed, the job runs within seconds, under its own key, and the answer does not wait for it. A thrown
245
256
  handler, a refused answer and a failed commit kick nothing. Kicks coalesce: at most one run is active and one pending,
246
257
  however many calls arrive. A kick carries nothing; the job reads its rows, and its schedule stays the recovery.
258
+ The kick is written in the site's transaction, so a crash right after the commit still runs the job.
247
259
  `kicks` names cron jobs of the contract, as literals (`r.mutation({ …, kicks: ['testMails'] })`); a mutation, a
248
260
  webhook and a job declare it, and the kick edges never form a cycle.
249
261
 
262
+ **A kick for later.** `ctx.kick('<job>', { at })`, with `at` a `Date`, runs the job at that time instead of after the
263
+ commit: a reminder, a retry the application times itself. Kicks of one job in the same second are one; kicks at
264
+ different times stay apart, and a run takes only those already due. The second argument is the time and nothing else;
265
+ what to do stays in the job's rows (`where <due> <= now()`, or a queue table's `<due>`). On Cloudflare the object's
266
+ alarm runs it within seconds of `at`; on Bun the serving process that wrote it runs it at `at`, and another process
267
+ finds it within a minute.
268
+
250
269
  The rules of the job:
251
270
 
252
271
  - **Bounded batches.** Each run takes at most a fixed number of records (`order by received_at, id limit 50`), oldest
@@ -12,7 +12,7 @@ longer writes. Commit them; never edit, format or import them (`generated-test-h
12
12
  `app` or `creates` endpoint refuses a holder of its action in one scope only (403) and answers a global holder. An
13
13
  endpoint of several `capabilities` adds a denied case per capability. A public procedure answers anyone without a
14
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.
15
+ of its kind, or as the file the fixtures name (`files`, below); a `GET` procedure's input goes in its URL.
16
16
  - Their kit stands in for IAM, as `testKit` does (below): it creates a scope, assigns or invites a member and issues a
17
17
  link under IAM's rules for the caller's grants. A repeated invitation answers the open one, `resend` restarts its
18
18
  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`
@@ -67,6 +67,27 @@ export const members = { 'api.tasks.assign': ['assignee'] }
67
67
  to another holds that row's key. A text column may be given; the key, the version, the creator and a file column may
68
68
  not (a file column holds a live, scanned file). Only application tables, and only for an endpoint with a leak or an
69
69
  own-object case: the checker refuses a table in a scope, which `rows` and `seeds` address (`endpoint-fixture`).
70
+ - `files['<endpoint id>']` names, by file field, a file of the repository that every case of the endpoint sends there
71
+ instead of the generated one, a path from the application's root:
72
+ `export const files = { 'api.skills.publish': { package: 'src/__tests__/fixtures/skill.zip' } }`. Give one when the
73
+ handler inspects the content (a package it unpacks, a document it parses) and answers 400 to the generated file, which
74
+ 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
75
+ 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
76
+ checker refuses a field that holds no file and a path that leaves the application, starts with `.` or has characters
77
+ other than letters, digits, `_`, `-`, `.` and `/` (`endpoint-fixture`).
78
+ - `pins['<endpoint id>']` gives text columns of the row the endpoint addresses (the row of the table that owns its
79
+ dimension) a known value instead of the seed's marker: `export const pins = { 'api.skills.publish': { slug:
80
+ 'published-skill' } }`, when the handler ties the column to the input or to the file in `files` (a package whose
81
+ `SKILL.md` names the skill's slug). The own scope's row holds the value, the other scope's `<value>-other`, which a
82
+ 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,
83
+ fails the case; the checker refuses one of an endpoint without an addressed row (`endpoint-fixture`).
84
+ - `refusals['<endpoint id>']` lists the error types of the 400s the endpoint's handler answers with when its rule ties
85
+ the row to the input and the scope is the other one: `export const refusals = { 'api.skills.publish':
86
+ ['skill_frontmatter'] }`, beside the pin above. A leak case asks from the other scope first, whose pinned value the
87
+ package does not name; that request may answer one of them. The own case passes on 200 or one of them, and the
88
+ denial cases still expect 404 or 403. The answer a leak case checks, the own scope's, still fails on it, because an
89
+ answer that holds nothing proves no isolation: pin the row and give the file so that the own scope succeeds. Any
90
+ other 400 fails the case, and the checker refuses `validation`, an input the schema refuses (`endpoint-fixture`).
70
91
  - The endpoint id is `<mount>.<group>.<endpoint>` (`api.tasks.close`).
71
92
  - The seed of the tests fills every text column with a marker and every other required column with a sample of its
72
93
  type: an enum's first label, `1`, `false`, today. A column with a `DEFAULT` keeps it (`status` is `open`). A column
@@ -301,6 +322,13 @@ if (postgres !== null) {
301
322
  - A mutation that kicks (`kicks`, `ctx.kick`) starts its job in the background of the call. `kit.drain()` waits for
302
323
  those runs, and `kit.runJob` first waits for them; every generated access case drains before it answers. The kicked
303
324
  run may start at once, so arm a fault before the call, never between the call and the run.
325
+ - `await kit.runDueJobs({ within: 3 * 3600000 })` runs every job with a wake due now or within `within` milliseconds
326
+ (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.
327
+ It answers `[{ job, result }]` for the runs it started, and first waits for the kicked runs. Without it the kit fires
328
+ no wake: a cron job runs only through `runJob` or `runDueJobs`. Only the wakes move, never the clock: a handler's
329
+ `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
330
+ 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
331
+ second for the first retry, so `runDueJobs({ within: 2000 })` runs it. It needs the application's data layer.
304
332
  - `kit.mail` is the stand-in for every job's mail transport (`MemoryEmailSender` of `@fabrika/app/testing`), so a test
305
333
  needs no mail variable. `kit.mail.accepted` is what reached the inbox, once per key, and `kit.mail.handoffs` every
306
334
  send with its `answer`. `refuse(code?)`, `unavailable()`, `unreachable()`, `loseAnswers(n)` and `during(hook)`
package/src/build.ts CHANGED
@@ -25,7 +25,12 @@ export type EntryRuntime = 'bun' | 'cloudflare'
25
25
  export * from './build-recipe.js'
26
26
 
27
27
  // In a module of their own, which the Worker imports without this one's file system.
28
- export { CLOUDFLARE_APPLICATION_BINDING, CLOUDFLARE_APPLICATION_CLASS, CLOUDFLARE_FILES_BINDING } from './cloudflare/names.js'
28
+ export {
29
+ CLOUDFLARE_APPLICATION_BINDING,
30
+ CLOUDFLARE_APPLICATION_CLASS,
31
+ CLOUDFLARE_ASSETS_BINDING,
32
+ CLOUDFLARE_FILES_BINDING,
33
+ } from './cloudflare/names.js'
29
34
 
30
35
  const HEADER = '// @generated by `fabrika app build` from src/app.ts. Do not edit: every build rewrites it.'
31
36