@fabrika/app 0.3.2 → 0.4.0

package/skill/references/errors.md

@@ -0,0 +1,108 @@
+# references/errors.md — what the checker, the compiler and the runtime tell you
+
+## The checker: refusals and hints
+
+`bunx fabrika-check .` prints one finding per line, `<file>:<line>:<col> <rule> <what> (allowed form: <fix>)`.
+Refusals come first and fail the check; hints follow under their own heading and do not. Fix both: a hint is the
+architecture, and a refusal's allowed form is the one fix that passes. There is no suppression syntax.
+
+The refusals agents meet most, and their fix:
+
+| Rule                  | Means                                                                                                                                                            | Fix                                                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `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(…)`  |
+| `contract`            | the contract does not compile (a reserved role, an unknown action, a wrong field)                                                                                | the message names the field                                                             |
+| `package-replacement` | `package.json` names the app under `@fabrika/*`, or a dependency is `workspace:*`                                                                                | another name; a registry range such as `^0.0.4`                                         |
+| `generated-test-hash` | a generated test is missing, edited or stale                                                                                                                     | `bunx fabrika db test-scaffold`, and commit what it writes                              |
+| `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`)        |
+| `raw-sql`             | a driver's `sql` (imported from `bun`, Kysely, `postgres`)                                                                                                       | the handles, or `sql: 'read'` and `ctx.sql`                                             |
+| `forbidden-import`    | a driver, an S3 client, `jose`, `node:http`, `child_process`                                                                                                     | the handles, a file collection, a connector                                             |
+| `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   |
+| `env-read`            | `process.env`, `Bun.env`                                                                                                                                         | `defineDeps(build)`, which receives the application's variables                         |
+| `client-identity`     | an input field `userId`, `ownerId`, `createdBy`, `tenantId`, `workspaceId`                                                                                       | the access form's `from`, `ctx.principal.id`, or `createdBy` in the policy              |
+| `type-assertion`      | `as T` (other than `as const`), `<T>x`                                                                                                                           | fix the type; `fromRow` parses a row into a schema's type                               |
+| `sensitive-log`       | a log of an error object, a request, headers or the environment                                                                                                  | log a short fixed message                                                               |
+| `migration-name`      | a migration not named `YYYYMMDDHHMMSS_slug.sql` (UTC)                                                                                                            | `bunx fabrika db new <slug>`                                                            |
+| `test-only-import`    | `@fabrika/app/testing` or `@fabrika/db/testing` outside a test file                                                                                              | import them only from `*.test.ts` or `__tests__/`                                       |
+| `spa-server-import`   | the SPA loads a server module                                                                                                                                    | the SPA imports `@fabrika/app/client`, the contract, `src/schemas.ts` and `src/shared/` |
+| `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                          |
+| `skipped-test`        | `.skip`, `.only`, `.todo`                                                                                                                                        | run the test                                                                            |
+
+The hints:
+
+| Hint                   | Means                                                         | Fix                                                         |
+| ---------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
+| `handler-location`     | a `.handle(…)` outside a slice's `endpoints.ts`               | move the endpoint into `src/<slice>/endpoints.ts`           |
+| `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` |
+| `logic-data-access`    | `logic.ts` reaches data                                       | keep `logic.ts` pure; pass it plain values                  |
+| `cross-slice-queries`  | a slice loads another slice's `queries.ts`                    | move the function, or call that slice's endpoint            |
+| `sql-undeclared`       | `ctx.sql` in a handler whose endpoint declares no `sql`       | add `sql: 'read'` (or `'write'`) to that endpoint           |
+
+The first run may report only the contract's refusals: the generated-test findings appear once the contract compiles.
+
+## Type errors
+
+A kit error lands on the line of the mistake, in one or two lines that name the fix. Read the last line first.
+
+| The compiler says                                                               | Fix                                                                     |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `add .handle(…) to tasks.get: every endpoint takes its handler beside it`       | add the handler; when the handler exists, fix the error inside it first |
+| `the handler returns version, which the output does not declare`                | return only the output's fields                                         |
+| `… where the output is camelCase: map it with fromRow(Schema, row)`             | `fromRow(Schema, row)`                                                  |
+| `update on tasks needs the action 'tasks.write', and this endpoint holds '…'`   | the endpoint's action, a column write action, or a separate endpoint    |
+| `getForUpdate locks the row, so it runs only in a mutation`                     | `r.mutation`                                                            |
+| `update acts on one object: declare access with on`                             | access `on`, not `in` or `over`                                         |
+| `tasks is not under in: 'org' (it lies in project): declare …`                  | the access form the message names                                       |
+| `ctx.sql needs a declaration: add sql: 'read' …`                                | declare `sql` on the endpoint                                           |
+| `tasks is outside this site's scope: declare unscoped: { tasks: 'read' } on it` | declare it, or use the capability's handles                             |
+| `a job writes inside ctx.transaction((tx) => …): use tx.db there`               | move the write into the transaction                                     |
+| `listing the members of org needs the action '…'; get(principalId) checks one`  | `ctx.members.get(id)`, or an endpoint of the directory's `members.list` |
+| `neither task nor a dimension containing it declares members`                   | declare `members` on the dimension whose people the endpoint picks      |
+| `'member.label' is possibly 'null'`                                             | a nullable column or output; only `directory: 'labels'` makes it text   |
+| `admin is a role IAM defines itself for every application (reserved: admin)`    | another role name                                                       |
+| `Property 'id' does not exist on type 'Ref<…>'`                                 | `ctx.target.value`                                                      |
+| `Property 'margin' does not exist on type 'Omit<DealsTable, "margin">'`         | the column has its own read action, which this capability lacks         |
+| `Type 'Date' is not assignable to type 'string'` on a `date` column             | a `YYYY-MM-DD` string                                                   |
+| `Cannot find module '@fabrika/…'` and implicit `any`s everywhere                | `bun install` (at the repository root in a monorepo)                    |
+
+## Runtime answers
+
+A procedure, a form, a webhook and a file collection answer JSON in an envelope: a 200 is `{ result: <output> }` (a
+procedure's output, a form's `{ received: true }`, a file list's `{ items, next }`), any other status
+`{ error: { type, message } }`. The typed client unwraps it; a plain `fetch` (a form, a test) reads `result`. A health
+check (`{ status: 'ok' }`) and the SPA's browser configuration answer without one.
+
+| Answer | Comes from                                                                                                                                                                                                                               |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 400    | the input does not match its schema; `BadRequestError`                                                                                                                                                                                   |
+| 401    | no valid credential. In a test, the caller is missing                                                                                                                                                                                    |
+| 403    | the caller lacks the action, or for `in` the scope: a missing grant, never a bug to code around; `ctx.members.list()` below the org for a caller without the list action on the org itself; a path no endpoint declares                  |
+| 404    | `on`: the object does not exist or is not the caller's, also when a concurrent delete removed it first; `NotFoundError`                                                                                                                  |
+| 409    | a stale `expectVersion`; `ConflictError`; a lost `getForUpdate` race                                                                                                                                                                     |
+| 500    | a throw without a numeric `httpStatus` below 500, a `type` and a `message`, a refused statement, a call of `ctx.sql` the endpoint does not declare (`undeclared_reach`), a `ctx.sql` row the schema refuses (`count(*)` without `::int`) |
+| 503    | IAM cannot be asked, or the member directory has no transport                                                                                                                                                                            |
+
+An undeclared path is 403 at the proxy, also for a signed-in caller who holds every action: the proxy serves only the
+contract's endpoints, picks the most specific one, and never falls through to a broader one. A test that asks for a
+route you did not declare (an edit that does not exist) expects 403, not 404. An unknown procedure that reaches the
+application under an RPC prefix is 404, but the proxy stops it first.
+
+A connector call is not an HTTP answer: it resolves to an outcome (`references/webhooks-links-connectors.md`), and the
+handler decides what to answer. Any thrown value with a numeric `httpStatus` below 500, a `type` and a `message` (an
+`HttpError` of `@fabrika/app`, such as `ForbiddenError`, or a plain object of those fields) answers its own status
+with its message; throw the three business errors for the application's own refusals.
+
+A 500 answers a fixed message; the server log has one line, `fabrika: <endpoint>: <code>: <reason>: <text>`, with a
+fixed failure code and, for a framework refusal, its reason and the reason's fixed text, never a value or your error's
+message. The codes you meet most:
+
+| Code                 | Means                                                                                                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 |
+| `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`)    |
+| `handler_failed`     | your handler threw something else; the log has no more, so test the handler                                                                                                           |
+
+With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. A job attempt names its failure with the
+same codes and reasons: `fabrika job run` prints `job <name> failed after 1 attempt: query_refused: undeclared_reach`,
+its log line adds the text, and `kit.runJob` answers `{ status: 'failed', code, reason }`. A `DatabaseError` carries
+only the SQLSTATE: `23505` is a unique violation, `23503` a foreign key, `23502` a null in a `NOT NULL` column.

package/skill/references/files.md

@@ -0,0 +1,335 @@
+# references/files.md — file collections
+
+A file collection attaches uploaded files to the rows of one table that owns a dimension. It is a section of the
+contract with generated endpoints: no handler, no storage client, no URL of your own.
+
+```ts fabrika.contract.ts
+import { app } from './src/app-kit'
+import { comments } from './src/comments/endpoints'
+import { members } from './src/members/endpoints'
+import { priorities } from './src/priorities/endpoints'
+import { projects } from './src/projects/endpoints'
+import { reports } from './src/reports/endpoints'
+import { digest } from './src/tasks/digest'
+import { tasks } from './src/tasks/endpoints'
+import { erase } from './src/tasks/erase'
+
+export const contract = app.contract((c) => ({
+	api: c.rpc('/api', {
+		projects,
+		tasks,
+		comments,
+		reports,
+		members,
+		priorities,
+	}),
+	files: {
+		attachments: c.files({
+			owner: 'tasks',
+			read: 'tasks.read',
+			write: 'tasks.write',
+			delete: 'tasks.write',
+			maxBytes: 5242880,
+			types: ['image/png', 'image/jpeg', 'application/pdf', 'text/plain'],
+			maxPerOwner: 20,
+		}),
+	},
+	jobs: { digest, erase },
+	health: c.health('/healthz'),
+}))
+```
+
+The collection serves, for signed-in people only:
+
+| Endpoint                                     | Access                      | Does                                                                    |
+| -------------------------------------------- | --------------------------- | ----------------------------------------------------------------------- |
+| `POST /api/files.attachments.upload/:taskId` | `write` on the task         | the body is the file, `?name=` its name; answers `{ result: { id } }`   |
+| `GET /api/files.attachments/:fileId`         | `read` on the file's task   | streams the file                                                        |
+| `POST /api/files.attachments.list`           | `read` on the task          | body `{ owner, limit?, after? }`; answers `{ result: { items, next } }` |
+| `POST /api/files.attachments.remove`         | `delete` on the file's task | body `{ id }`                                                           |
+
+A file reaches what its task reaches, now: a moved task moves its files. The list answers the task's files oldest
+first, each `{ id, name, type, size, status, createdAt }`, at most `limit` (1–100, default 50) after the id `after`.
+
+The SPA calls them through the typed client, never a hand-written `fetch`: `api.files.attachments` of
+`createClient(contract, 'api')`, and on a link mount's client the `link: true` collections, without the owner.
+
+```ts web/attachments.ts
+import { createClient, RpcError } from '@fabrika/app/client'
+import { contract } from '../fabrika.contract'
+
+const api = createClient(contract, 'api')
+
+/** Uploads `file` to the task, then lists its files; a file's `type` is the declared media type. */
+export const attach = async (
+	taskId: string,
+	file: File,
+	list: HTMLElement,
+): Promise<void> => {
+	try {
+		await api.files.attachments.upload(taskId, file)
+		const page = await api.files.attachments.list({ owner: taskId })
+		list.replaceChildren(
+			...page.items.map((item) =>
+				Object.assign(document.createElement('li'), {
+					textContent: `${item.name ?? 'file'} (${item.status})`,
+				})
+			),
+		)
+	} catch (error) {
+		list.textContent = error instanceof RpcError
+			? `Refused: ${error.type}`
+			: 'Failed'
+	}
+}
+```
+
+`download(id)` answers a `File` named as it was uploaded (409 `quarantined` while a scan runs), and `remove({ id })`
+removes one. `ResultOf<typeof api.tasks.get>` and `InputOf<typeof api.tasks.create>` of `@fabrika/app/client` name a
+procedure's answer and input for a view that maps them.
+
+## From a handler or a job: `ctx.files`
+
+`ctx.files('<collection>')` reaches one collection of the contract from a handler, a job's `ctx` and its `tx`. Each
+call takes a `Ref` of the owner (a task here), for one of the collection's actions:
+
+| Call                              | Takes the owner's `Ref` for | Answers                                                                    |
+| --------------------------------- | --------------------------- | -------------------------------------------------------------------------- |
+| `list(owner, { after?, limit? })` | `read`                      | `{ items, next }`, the files the list endpoint answers; `createdAt` a Date |
+| `open(owner, id, { maxBytes })`   | `read`                      | `{ id, name, type, size, bytes }` of one live file, read whole             |
+| `removeAll(owner)`                | `delete`                    | how many files it marked removed                                           |
+
+A Ref for another action, or of another dimension, is refused. `open` answers 404 for a file of another owner, a
+removed or a rejected one, 409 `quarantined` while the scan has not called it clean, and 413 for a file over
+`maxBytes`, before any byte is read. Pass the size you hold in memory, at most the collection's `maxBytes`. The name
+is checked when the call runs, not by the types: a name the contract does not declare is a 500.
+
+Every call needs the collection's `read`, so a write capability alone sees no file. A mutation that requires a
+document is declared with an action that is the collection's `read` too, or the check runs where the caller holds
+`read`: never mint or widen a capability to list.
+
+A job mints the owner's `Ref` with `ctx.ref` and opens each live file, here to attach it to an e-mail of `deps`:
+
+```ts src/tasks/digest.ts
+import { app } from '../app-kit'
+import { mailer } from '../mail'
+
+/** The largest report one e-mail carries: the collection's maxBytes. */
+const REPORT_MAX_BYTES = 5242880
+
+export const digest = app.cron('0 6 * * *', {
+	actions: ['tasks.read'],
+	scope: 'app',
+})
+	.handle(async ({ ctx }) => {
+		const mail = mailer.get()
+		const tasks = ctx.db.over(ctx.within('tasks.read', 'project')).tasks
+		const done = await tasks.list({ where: [['status', '=', 'done']], limit: 50 })
+		for (const task of done.items) {
+			const owner = await ctx.ref('tasks.read', 'task', task.id)
+			const files = ctx.files('attachments')
+			const page = await files.list(owner)
+			const reports = []
+			for (const file of page.items.filter((item) => item.status === 'live')) {
+				reports.push(
+					await files.open(owner, file.id, { maxBytes: REPORT_MAX_BYTES }),
+				)
+			}
+			ctx.signal.throwIfAborted()
+			await mail.sendReports(task.title, reports, ctx.signal)
+		}
+	})
+```
+
+```ts src/mail.ts
+import { defineDeps } from '@fabrika/app/implement'
+
+export interface Report {
+	readonly name: string | null
+	readonly type: string
+	readonly bytes: Uint8Array
+}
+
+export interface Mailer {
+	/** Sends the reports of one task; throws when the provider refuses, and gives up once `signal` aborts. */
+	sendReports(
+		title: string,
+		reports: readonly Report[],
+		signal: AbortSignal,
+	): Promise<void>
+}
+
+const variable = (env: Readonly<Record<string, unknown>>, name: string) => {
+	const value = env[name]
+	if (typeof value !== 'string' || value === '') {
+		throw new Error(`the application variable ${name} is not set`)
+	}
+	return value
+}
+
+export const mailer = defineDeps((env): Mailer => ({
+	async sendReports(title, reports, signal) {
+		const response = await fetch(variable(env, 'MAIL_API_URL'), {
+			method: 'POST',
+			headers: {
+				Authorization: `Bearer ${variable(env, 'MAIL_API_KEY')}`,
+				'Content-Type': 'application/json',
+			},
+			body: JSON.stringify({
+				to: variable(env, 'REPORTS_TO'),
+				subject: `Reports of ${title}`,
+				attachments: reports.map((file) => ({
+					filename: file.name ?? 'report',
+					contentType: file.type,
+					content: Buffer.from(file.bytes).toString('base64'),
+				})),
+			}),
+			signal,
+		})
+		if (!response.ok) {
+			throw new Error(`the mail provider answered ${response.status}`)
+		}
+	},
+}))
+```
+
+```ts src/app.ts
+import { serve } from '@fabrika/app/implement'
+import { scoped } from '@fabrika/db'
+import { contract } from '../fabrika.contract'
+import { tables } from './db/tables'
+import { mailer } from './mail'
+
+export default serve(contract, { database: scoped(tables), deps: mailer })
+```
+
+`removeAll` runs in a mutation and in a job's `tx.files`, in the same transaction as the handler's writes: an erasure
+that blanks a record and removes its files keeps both or neither. A query and a job's `ctx.files` only read. The
+framework's sweep deletes the removed files' objects within the hour, and so the objects of a deleted owner's files.
+
+```ts src/tasks/erase.ts
+import { app } from '../app-kit'
+
+/** Blanks the title of every task closed more than a year ago, and removes its attachments with it. */
+export const erase = app.cron('30 2 * * *', {
+	actions: ['tasks.read', 'tasks.write'],
+	scope: 'app',
+})
+	.handle(async ({ ctx }) => {
+		const yearAgo = new Date(Date.now() - 365 * 86_400_000).toISOString().slice(
+			0,
+			10,
+		)
+		const tasks = ctx.db.over(ctx.within('tasks.read', 'project')).tasks
+		const stale = await tasks.list({
+			where: [['status', '=', 'done'], ['due_on', '<', yearAgo], [
+				'title',
+				'<>',
+				'',
+			]],
+			limit: 100,
+		})
+		for (const task of stale.items) {
+			const ref = await ctx.ref('tasks.write', 'task', task.id)
+			await ctx.transaction(async (tx) => {
+				const locked = await tx.db.on(ref).getForUpdate()
+				await tx.db.on(ref).update({ title: '' }, { expectVersion: locked.version })
+				await tx.files('attachments').removeAll(ref)
+			})
+		}
+	})
+```
+
+- The owner is a table with a dimension scope; an application table owns no collection.
+- There is no limit on the bytes of one owner's files together: `maxPerOwner` × `maxBytes` bounds them.
+
+## Malware scan
+
+`scan: true` on a collection holds every upload `quarantined` until ClamAV answers clean; on Zerops the platform
+installs ClamAV and runs the scan job. The download answers 409 `quarantined` until then and 404 once the file is
+`rejected`; the list shows each file's `status`, so show it rather than a broken link. In a test, the scan runs with
+`kit.runJob(FILE_SCAN_JOB)` and a `scanner` passed to `testKit` (`references/tests.md`); the generated tests pass their
+own seeded files.
+
+- A scanning collection admits at most 100 MiB per file (`maxBytes`) and not `application/gzip`; an empty upload is
+  400 `empty`.
+- A ZIP or Office document must start with the ZIP header. Any other file that holds a ZIP signature anywhere is
+  rejected, even a rare harmless PDF or image; that is the fail-closed cost.
+- A table written by the `fileTableSql` below can already hold the scan states: turning `scan` on needs no migration.
+  Only a table created by an earlier two-state `fileTableSql` (its check names `'pending', 'live'` alone) needs
+  `fileScanSql('<name>')` of `@fabrika/db` in a new migration, and `fabrika-check` names it. On a current table that
+  migration fails: it adds the constraint, columns and index again.
+- ClamAV holds about 1 GB of signatures in memory. On Zerops the deploy service must declare
+  `verticalAutoscaling: { minRam: 2 }` (GB), or the build refuses the application. Zerops ignores a changed `verticalAutoscaling` of an existing service on a re-import:
+  raise an existing service's RAM through Zerops itself.
+
+```text
+// the deploy service in the services of fabrika.config.ts
+{
+	hostname: 'tasksapi',
+	type: 'alpine/bun@1.3',
+	priority: 10,
+	enableSubdomainAccess: false,
+	minContainers: 1,
+	maxContainers: 2,
+	verticalAutoscaling: { minRam: 2 },
+}
+```
+
+## Its table
+
+Each collection has a table `fabrika_files_<name>`, created by an application migration. Write exactly the DDL that
+`fileTableSql` of `@fabrika/db` returns. `key` and each `chain` entry are `{ column, type }`, with `type` `'uuid'` or
+`'text'` as the owner table declares the column, the nearest container first:
+
+```bash
+bun -e "import { fileTableSql } from '@fabrika/db'; console.log(fileTableSql('attachments', { table: 'tasks', key: { column: 'id', type: 'uuid' }, chain: [{ column: 'project_id', type: 'uuid' }, { column: 'org_id', type: 'text' }] }))"
+```
+
+```sql db/migrations/20261012100000_attachments.sql
+CREATE TABLE fabrika_files_attachments (
+	id UUID PRIMARY KEY,
+	owner_id UUID,
+	project_id UUID,
+	org_id TEXT,
+	status TEXT NOT NULL CONSTRAINT fabrika_files_attachments_status CHECK (status IN ('pending', 'live', 'quarantined', 'rejected')),
+	object_key TEXT NOT NULL UNIQUE,
+	size BIGINT,
+	content_type TEXT NOT NULL,
+	sha256 TEXT,
+	original_name TEXT,
+	created_by TEXT NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL,
+	deleted_at TIMESTAMPTZ,
+	object_version TEXT,
+	scan_attempts INTEGER NOT NULL DEFAULT 0,
+	scan_after TIMESTAMPTZ,
+	FOREIGN KEY (owner_id, project_id, org_id) REFERENCES tasks (id, project_id, org_id) ON UPDATE CASCADE ON DELETE SET NULL
+);
+CREATE INDEX fabrika_files_attachments_owner ON fabrika_files_attachments (owner_id) WHERE deleted_at IS NULL;
+CREATE INDEX fabrika_files_attachments_removable ON fabrika_files_attachments (created_at) WHERE deleted_at IS NOT NULL OR owner_id IS NULL OR status = 'pending';
+CREATE INDEX fabrika_files_attachments_scan ON fabrika_files_attachments (scan_after) WHERE status = 'quarantined';
+```
+
+- The owner table needs `UNIQUE (<key>, <chain columns>)`; `tasks` has `UNIQUE (id, project_id, org_id)`.
+- Codegen leaves the table out, and no policy names it: only the framework reads it.
+- The name is lowercase snake_case, at most 39 characters.
+- `link: true` serves a link mount's holders, for the mount's own object: `POST <prefix>/api/files.<name>.upload`,
+  `POST <prefix>/api/files.<name>.list` (no `owner`) and `GET <prefix>/api/files.<name>/:fileId` under every link mount bound to the owner's dimension, which must grant the
+  collection's `write` and `read`. The owner is the link's object, never a parameter.
+- `link: ['completion']` serves the named link mounts only. Name them when the owner's dimension has a link meant
+  for something else (a one-click answer): a mount the list does not name has no file route and need not grant
+  the collection's actions. Its holder gets 403 from the proxy, which finds no endpoint for the path.
+
+## Storage
+
+On Zerops, declare one `object-storage` service in `fabrika.config.ts`; the platform writes `FABRIKA_APP_STORAGE_*`
+from it. Never read those variables, build a storage URL or import an S3 client.
+
+```text
+// in the services of fabrika.config.ts
+{ hostname: 'tasksfiles', type: 'object-storage', objectStorageSize: 1, priority: 50 }
+```
+
+A test that boots an application with files passes `files: new MemoryFileObjects()` (`@fabrika/platform/testing`) to
+`testKit`.

package/skill/references/jobs.md

@@ -0,0 +1,169 @@
+# references/jobs.md — cron jobs
+
+Background work is a cron job: `app.cron(schedule, { actions, scope: 'app' })` with its `.handle(…)` in the
+`endpoints.ts` of the slice whose data it works on, mounted under `jobs` in the contract. There are no timers, loops,
+`setInterval` or self-scheduled work, and no `ctx.jobs.enqueue`: work for later is a row that the next run picks up.
+
+```ts src/overdue/endpoints.ts
+import { app } from '../app-kit'
+import { isOverdue } from './logic'
+
+/** Marks every open task past its due day, hourly; each is re-read under its lock, so a concurrent change is skipped. */
+export const markOverdue = app.cron('15 * * * *', {
+	actions: ['tasks.read', 'tasks.write'],
+	scope: 'app',
+	timeout: '10m',
+	retries: 2,
+})
+	.handle(async ({ ctx }) => {
+		const today = new Date().toISOString().slice(0, 10)
+		const tasks = ctx.db.over(ctx.within('tasks.read', 'project')).tasks
+		let after: string | undefined
+		do {
+			const page = await tasks.list({
+				where: [
+					['overdue', '=', false],
+					['status', '<>', 'done'],
+					['due_on', '<', today],
+				],
+				limit: 100,
+				after,
+			})
+			for (const task of page.items) {
+				const ref = await ctx.ref('tasks.write', 'task', task.id)
+				await ctx.transaction(async (tx) => {
+					const locked = await tx.db.on(ref).getForUpdate()
+					if (isOverdue(locked, today)) {
+						await tx.db.on(ref).update({ overdue: true }, {
+							expectVersion: locked.version,
+						})
+					}
+				})
+			}
+			after = page.next ?? undefined
+		} while (after !== undefined)
+	})
+```
+
+The list's filter and the decision under the lock are one rule, a pure function of `logic.ts`. A task someone closed,
+postponed or cleared the due day of between the list and the lock is left alone:
+
+```ts src/overdue/logic.ts
+/** An open task not yet marked, whose due day (`YYYY-MM-DD`) is before `today`. */
+export const isOverdue = (
+	task: {
+		readonly status: 'open' | 'doing' | 'done'
+		readonly overdue: boolean
+		readonly due_on: string | null
+	},
+	today: string,
+): boolean =>
+	task.status !== 'done' && !task.overdue && task.due_on !== null
+	&& task.due_on < today
+```
+
+```ts src/overdue/__tests__/logic.test.ts
+import { expect, test } from 'bun:test'
+import { isOverdue } from '../logic'
+
+test('a task is overdue only while open, unmarked and due before today', () => {
+	const task = { status: 'open', overdue: false, due_on: '2026-10-01' } as const
+	expect(isOverdue(task, '2026-10-12')).toBe(true)
+	expect(isOverdue({ ...task, due_on: '2026-10-12' }, '2026-10-12')).toBe(false)
+	expect(isOverdue({ ...task, due_on: '2099-01-01' }, '2026-10-12')).toBe(false)
+	expect(isOverdue({ ...task, due_on: null }, '2026-10-12')).toBe(false)
+	expect(isOverdue({ ...task, status: 'done' }, '2026-10-12')).toBe(false)
+	expect(isOverdue({ ...task, overdue: true }, '2026-10-12')).toBe(false)
+})
+```
+
+```ts fabrika.contract.ts
+import { app } from './src/app-kit'
+import { comments } from './src/comments/endpoints'
+import { members } from './src/members/endpoints'
+import { markOverdue } from './src/overdue/endpoints'
+import { priorities } from './src/priorities/endpoints'
+import { projects } from './src/projects/endpoints'
+import { reports } from './src/reports/endpoints'
+import { tasks } from './src/tasks/endpoints'
+
+export const contract = app.contract((c) => ({
+	api: c.rpc('/api', {
+		projects,
+		tasks,
+		comments,
+		reports,
+		members,
+		priorities,
+	}),
+	jobs: { markOverdue },
+	health: c.health('/healthz'),
+}))
+```
+
+- The schedule is five cron fields, UTC. `scope: 'app'` is the only scope: a job reaches every value.
+- A job holds exactly its `actions`. `ctx.within(action, dimension)` is a `Within` of every value;
+  `ctx.ref(action, dimension, id)` locates one object (404 when it is gone). Bind them with `ctx.db.over(within)`,
+  `ctx.db.in(ref)` and `ctx.db.on(ref)`.
+- `ctx.within` names the dimension an endpoint's `over` would: the nearest of the rows' chain (tasks lie in a
+  project: `'project'`; `references/endpoint.md`). A job holds every value, so a farther one reaches the same rows;
+  the rule keeps a job's capability the same as the list endpoint's. `ctx.ref` names the row's own dimension (`'task'`).
+- "Today" is the UTC day (`new Date().toISOString().slice(0, 10)`), so a task turns overdue at the first run after its
+  due day ends in UTC, hours off an org's own midnight. When the product needs the org's day, ask the human: the
+  zone is a new column (an IANA name). The decision under the lock then takes the org's day, computed in `logic.ts`
+  with `new Intl.DateTimeFormat('en-CA', { timeZone: zone }).format(now)`, and the list filters with the UTC day plus
+  one, since no zone is a day further ahead.
+- **Reads run outside the transaction; every write runs inside `ctx.transaction((tx) => …)`**, through `tx.db`, fenced
+  by the attempt's lease. A write outside it is a type error that names `tx.db`.
+- An attempt that fails or outlives `timeout` (default 15 minutes) is retried up to `retries` times, so every write is
+  idempotent. **Re-read each row under its lock before you write it:** `tx.db.on(ref).getForUpdate()` inside the
+  transaction, decide again on what it answers with the list's whole filter (`isOverdue`), and write with its
+  `version`. The listed row is already old: someone
+  may have closed the task since, and writing with the listed version fails the whole attempt with a 409.
+- Paging over a filter the job's own writes change is safe: `after` is a keyset cursor on the key, so a row that
+  leaves the filter (`overdue` is now true) moves no other row to an earlier page.
+- A bulk write declares `sql: 'write'` on the job and runs `tx.sql` inside the transaction:
+
+  ``ctx.transaction((tx) => tx.sql(Marked)`update tasks set overdue = true, version = version + 1 where (…) returning id`)``
+
+  The version bump is yours to write. **A job writes no scope fragment**: it is app-wide (`scope: 'app'` is the only
+  scope), so `tx.sql.scope` of its `Within` would be every row.
+- `bun test --isolate` runs a job with `kit.runJob('markOverdue')` (`references/tests.md`). The platform runs
+  `fabrika job run <name>` from the crontab it generates; never write a crontab or read `FABRIKA_JOB_*`.
+- A job cannot create scopes or manage members, and has no `ctx.members`: a job holds no object chain. It issues share
+  links only when it declares `issues: '<link mount>'` and its actions hold the mount's `issuedBy` and every grant:
+  `ctx.links.issue(await ctx.ref('<issuedBy>', '<dimension>', id), { mount, days })`, and `ctx.links.revoke(id)` for
+  a link it issued. It is a widening for closer review. `references/public-intake.md` is the whole recipe: a form's
+  inbox, the record, the link and its e-mail, each step recorded before the next.
+- A job reads a file collection through `ctx.files('<collection>')` with a `Ref` it minted (`list`, `open` to attach a
+  file to an e-mail), and removes an owner's files only inside its transaction, `tx.files('<collection>').removeAll(ref)`
+  (`references/files.md`). The framework's own `fabrika-file-sweep` then deletes their objects; never write a sweep.
+- `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
+  each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
+- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, or a framework refusal
+  with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action`; `references/errors.md`).
+
+## An outbox: what a request asks a job to do
+
+A request handler calls no outside service (`references/endpoint.md`). It records what to do in a row, in its own
+transaction: a form's inbox row, or a state of its record (`link_state = 'due'`). A job does the work and calls the
+service. `references/public-intake.md` is the whole recipe; its rules:
+
+- **Bounded batches.** Each run takes at most a fixed number of records (`order by received_at, id limit 50`), oldest
+  first; the next run takes the rest.
+- **Claim a record where you consume it**: read it `for update skip locked` in the transaction that writes it, so a
+  row another session holds waits for a later run and blocks nothing behind it.
+- **Each record is its own work.** Run it in its own transactions, inside a `try`: a failure adds one to the record's
+  `attempts`, keeps a fixed step code in `last_failure` (never the error's message, which can quote a value), and the
+  run goes on with the next record. Rethrow when `ctx.signal` aborted: that failure is the attempt's, and the next
+  run meets the record as it is. So give each external call a deadline of its own inside the attempt's
+  (`AbortSignal.any([ctx.signal, AbortSignal.timeout(ms)])`): a call that hangs then fails its record, not the run.
+- **A dead state.** A record that failed `MAX_ATTEMPTS` times is dead: the batch skips it, the job logs it once by its
+  id (never an address), and an operator fixes or deletes it. Give the record a way back when the cause can go away
+  (a resend revives a dead delivery).
+- **A key on every external call**, derived from the record: the e-mail's `Idempotency-Key`, a provider's request id.
+  The provider then acts once per key, however often the job hands the call over. A retry sends the same request
+  under the same key: keep what it needs in the row until the call is known done (sealed, when it holds a secret).
+- **Each step recorded before the next effect**, so the next run finishes a stopped one.
+- An inbox needs a row key for this: `id UUID NOT NULL DEFAULT gen_random_uuid()`, since a form writes only its input
+  fields.