# @popcomputer/web 1.9.0: the agent rules and documentation in one file

The package's own AGENTS.md and docs/, as 1.9.0 ships them. Source: https://github.com/PatrickOgilvie/popcomputer-web. Quick start: https://web.popcomputer.com/llms.txt.

---

# @popcomputer/web for coding agents

Rules for writing an application on `@popcomputer/web`. Each rule names the one
API to use; the files in `docs/` beside this one explain each task, one short
file per task, and `docs/which-api.md` names the file for each. Every
TypeScript example here and in `docs/` type-checks against the package.

To use this file, point the application's own `AGENTS.md` or `CLAUDE.md` at
`node_modules/@popcomputer/web/AGENTS.md`. Replace a `CLAUDE.md` written for
another setup, such as the one `bun init` writes for `Bun.serve` and
`bun:sqlite`: its instructions contradict these. Keep one that already points
here, as the demo's does.

## Rules

1. **Declare once, in `setupWeb`, and register it.** `export const web =
   setupWeb(new Hono<Env>(), config)` in `src/app.ts` owns rendering, the
   database, auth, route binding parsers, pages, shared props, flash and the
   error page, and declares their types as values. Register it once with
   `declare module '@popcomputer/web' { interface Register { web: typeof web } }`;
   every other type derives from it. Never declare a type the config already
   declares. Declare the Worker's vars and secrets once, in `src/env.ts`,
   with `defineEnv` from `@popcomputer/web/env`: `secret(schema, {
   generate: randomSecret })` for a secret the app can make itself,
   `secret(schema)` for one someone sets, `variable(schema)` for a var, `{
   optional: true }` for one the Worker runs without. Type the bindings as
   `EnvBindings<typeof env>` and the other bindings beside it, and pass it
   as `setupWeb`'s `env`, which checks each isolate's bindings before it
   serves. Do not add framework middleware or register routes on the Hono
   app by hand.
2. **Every handler is an action.** Wrap an `Effect.gen` in `action(...)` and
   register it on the `routes` that `setupWeb` returns, or that
   `web.services(...)` returns with the application's own services:
   `routes.get/post/put/patch/delete(paths.project, action, { name })`.
   Declare every path once in `src/paths.ts` (`project: '/projects/{project}'`)
   and pass it as `setupWeb`'s `paths`, so `routes`, `redirect`, `back` and
   `href` accept only declared paths. Build every URL from it:
   `redirect(paths.project, { project: id })` in actions,
   `href(paths.project, { project: id })` from `@popcomputer/web/paths` in
   React. Registrations chain. `routes` accepts only actions whose services
   the setup provides.
3. **Declare every page's props as an Effect Schema** in `src/pages.ts` and
   pass the object as `setupWeb`'s `pages`. Take a table's columns from the
   table: `tableSchema(schema.projects).mapFields(Struct.pick(['id',
   'name']))` from `@popcomputer/web/schema`, and declare the signed-in user
   as `auth.session: betterAuthSession(tableSchema(schema.user))` (with
   `tableSchema(schema.session)` second when a plugin adds session fields),
   with Better Auth's `additionalFields: betterAuthFields(schema.user, { role: {
   input: false } })`. Type each React page as `WebPage<'Projects/Show'>`
   from `@popcomputer/web/react`; its props, the shared `auth.user` and
   `errors` follow. Type a form's fields as `FormInput<typeof Schema>`, from
   the schema its action validates. Declare props shared with every
   page in `shared`, computed when a page renders by
   `routes.provide(shareProps(effect))`, and flash values in `flash`.
4. **End every branch with a response helper:** `return yield* render(...)`,
   `redirect(...)`, `back(...)`, `json(Schema, value)`, `jsonOrRender(...)`,
   `file(...)`, `notFound(...)`, `forbidden(...)`, `invalid(...)` or
   `httpError(status, message, Schema, body)`. Declare an application cookie
   once, `cookie('cart', Schema, { path })`, and read, set and clear it
   through the declaration; sign one the server must trust
   (`signed: { secret: 'COOKIE_SECRET' }`), since an unsigned one holds
   whatever the visitor sends. `yield* flash(key, value)` before a redirect hands a
   message to the next page; a helper or guard layer that must send the
   visitor elsewhere fails with `redirectNow(path, params)`. Expected
   failures are typed Effect failures:
   turn a domain error into a response with `Effect.catchTags`, such as
   `invalid({ amount: error.message })` to show it beside its form field. A
   failure the action cannot answer, such as another system being down, is a
   defect: pipe that call through `Effect.orDie`, which answers 500 and hands
   the failure to the error observer; never over `authorize()`, `bound()`,
   `validateRequest` or the database, whose failures are answers. Give a page
   that reports a failure its status, `render('Signing/LinkInvalid', {},
   { status: 404 })`. A
   handler that ends differently per branch branches inside `Effect.gen`,
   whose branches TypeScript combines. Do not `throw` in an action. An
   endpoint's action (rule 13) returns its success value instead.
5. **Read request input only through `validateRequest(Schema)`,** or, in an
   endpoint's action, through its contract (rule 13). Build schemas
   from `@popcomputer/web/schema` validators (`requiredString`,
   `nullableString`, `coercedNumber`, `checkbox`, `email`, `uuid`, `isoDate`
   and `isoDateTime` for a day or a moment with its zone, ...), which
   accept form posts as well as JSON (an API rejects undeclared query
   parameters with `request: { order: ['query'] }, parseOptions: {
   onExcessProperty: 'error' }`), `nullable(...)` for a filter a GET form
   may send empty, and `upload({ types: [...] })` for files, served back with
   `file(...)`; a body over 1 MiB is refused, so an action taking larger
   files raises `validateRequest(Schema, { bodyLimit })`. A form that
   fails validation goes back to the page it came from (its Referer; without
   one, the page its route names, `routes.post(path, action, { form:
   paths.page })`, or its own path's page), which receives the
   field errors as `errors`; a JSON client gets a `422`. A key that route
   params, query and body provide with different values fails validation.
   Read headers and a raw body (a webhook signature) with `RequestService`.
6. **Load route models with `{param}` placeholders and `bound('param')`, and
   say in each binding who may load its record.** Name each model's Drizzle
   table in `setupWeb`'s `bindings` with `routeBinding` and one option:
   `routeBinding(schema.projects, { ownedBy: 'userId' })` for its owner only,
   a column that references `user.id` (anyone else gets the 404 a missing
   record gets, and a signed-out visitor is asked to sign in), `{ publicWhen: { visibility: 'public' } }` for
   anyone when its columns hold those values, `{ public: true }` for
   anyone, or `{ guarded: true }` when
   a guard layer decides, such as an organization's membership guard. Never
   check ownership in the action instead: a page anyone may see binds the
   table a second time, under its own name and path
   (`showcase: routeBinding(schema.projects, { publicWhen: { visibility: 'public' } })`).
   The model is the table's row, checked against its columns. Bind every
   record a path names, nested ones scoped to their parent with `scope`,
   whose option then decides, a membership by its user too
   (`/orgs/{organization:slug}/members/{member:userId}` with
   `member: routeBinding(schema.memberships, { scope: { organization: { foreignKey: 'organizationId' } } })`),
   and never read a record's id
   from the path to query for it yourself (a plain parameter, such as an
   invitation token, or the id of a record served from the data cache, is
   read with `validateRequest` and looked up like any input);
   to lock a bound record inside `dbTransaction`, read it again by its id with
   `.for('update')`. When the action needs the signed-in user, call
   `authorize()` before `bound()`: models load on the first `bound()` call,
   and a missing row is a 404. A record the user may not see answers 404,
   so its existence stays private; use
   `authorize((auth) => rule)` (a 403) for a record the user can see but not
   change. `bound('project')` type-checks only on a route whose path or
   prefix has `{project}`, in an action or in a layer guarding it.
7. **Authorize with `authorize()` or `authorize((auth) => rule, message)`.** Use
   `currentUser` when signing in is optional. A rule a group of routes shares
   is a `guard(...)` provided to it, `routes.provide(guard(effect))`; a
   membership guard finds the visitor's membership,
   `guard(CurrentMember, effect)`, and each action states the role or
   permission it needs, `yield* can('members.role')`, as `docs/guards.md`
   shows. Guard a group of routes from signed-out visitors with
   `routes.provide(RequireAuthLayer)`, which sends a signed-out visitor to
   `auth.signInPath`, or `routes.provide(RequireGuestLayer)`, which sends a
   signed-in one to `auth.homePath`. Validate a sign-in's password with
   `currentPassword`, which never trims it, and a new one with `password(...)`.
   Sign users in and up with an action that validates its form and returns
   `betterAuthRedirect('signInEmail', { body: input }, { redirectTo, errors })`
   from `@popcomputer/web/auth`, which sends the call through Better Auth's
   handler so the limits apply; call Better Auth for a result the action
   uses with `betterAuthCall(endpoint, { body })`. Never call `auth.api` from
   an action: it skips them. Both find the endpoint on Better Auth's
   instance, so give `auth.client` the instance, not a wrapper that loads
   Better Auth on first use. Limit password guessing with `setupWeb`'s
   `auth.signInLimits: { limiter: 'SIGN_IN_LIMITER', table: schema.rateLimit }`
   (a Workers Rate Limiting binding, and Better Auth's `rateLimit` table for
   each account's failures), sweep the table with
   `routes.scheduled(() => sweepSignInFailures)`, and keep
   `betterAuth({ rateLimit: { enabled: true, storage: 'memory' } })`. Keep
   `emailAndPassword: { enabled: true, requireEmailVerification: true }` and
   an `emailVerification.sendVerificationEmail` whose email tells a recipient
   who did not sign up to ignore it, with `autoSignInAfterVerification` off,
   as docs/auth.md's `createAuth` does: a password whose address nobody has
   proven then signs no one in. Its link opens a page whose button posts the
   token to the action that proves the address, so a mail scanner's fetch of
   the link proves nothing. Better
   Auth's plugins (organizations, two-factor, magic links, OAuth providers)
   stay Better Auth's: call their endpoints by name the same way, and email
   a magic link, as the verification link, to a page whose button posts its
   token. Sign in through an OAuth provider (`socialProviders`, or `genericOAuth` for a
   company's own) with `betterAuthRedirect('signInSocial', ...)`, and serve
   its callback alone, `routes.get(paths.authCallback, betterAuthHandler())`,
   with `account: { accountLinking: { disableImplicitLinking: true } }` and
   `onAPIError: { errorURL }` in `betterAuth`; register
   `routes.all(paths.authApi, betterAuthHandler({ settable }))` only for
   Better Auth's client SDK, naming the user fields visitors may set there,
   the application's `input: true` ones and plugins' such as `phoneNumber`. On D1, Better Auth writes each row in its own statement: write
   rows that must exist together, such as an organization and its owner, in
   your own `dbBatch`. Make the application's
   own record of a new member on their first visit, in a guard layer, since
   users from OAuth providers and magic links never pass through a sign-up
   action. A role a user
   holds per team or workspace lives on a membership row a guard layer
   reads (the organization plugin's `member` table), not on the user. Register a JSON
   API's routes on `routes.jsonApi()`, with their declared paths
   (`routes.jsonApi().provide(KeyAuth).get(paths.apiInvoices, ...)`), so every
   failure there answers JSON (a 401, not a redirect to sign in), and
   authenticate its keys in a layer that fails with
   `new UnauthorizedError({ message, challenge: 'Bearer' })`.
8. **Use the database only through `dbQuery`, `dbMutation`, `dbTransaction`
   and `dbBatch`:** `yield* dbQuery((db) => db.select()...)` to read,
   `dbMutation((db) => db.insert(...))` to write. Operations that must
   succeed together, with any Effect logic between them, go in
   `dbTransaction(Effect.gen(...))` (Postgres, MySQL, libsql); on Cloudflare
   D1, put the writes in one `dbBatch` and enforce limits inside the write
   statement, inserting a row only while a condition holds with
   `db.insert(table).select(db.select(rowOf(table, values)).from(...).where(condition))`. Write only validated input and values the server derives, and
   scope `where` clauses with bound models. State an invariant concurrent
   requests could break as a database constraint (`CHECK (stock >= 0)`, a
   unique idempotency key or webhook event id, or a trigger raising a named
   abort on D1) and handle `DatabaseConstraintViolation` by its `constraint`
   and `constraintName`, or show a named rule beside its fields with
   `constraintFieldErrors({ name: { field: 'message' } })`. Pipe a write through
   `uniqueFieldErrors({ column: 'message' })` to show a duplicate as a field
   error.
9. **Give the application's own services with `web.services({ app, request })`,**
   after registering `web`, in place of `export const { app, routes } = web`:
   `export const { app, routes } = web.services({ app: ProjectsLive, request:
   (c) => auditLogFor(c.env.KV) })`. The `routes` it returns accept actions
   that use them. `app` is for services built once and shared
   (configuration, in-memory caches), `request` for anything that holds the
   request's bindings (D1, KV, Hyperdrive). Define them with
   `Context.Service` and `Layer`, and read vars and secrets with
   `config.string('NAME')` and `config.redacted('KEY')`, Effect `Config`
   named by the Worker's bindings type, which reads the request's bindings.
   A layer's type is inferred, even when it uses `dbQuery`, `config` or
   `bound`.
10. **Run work that outlives the response with `background('name', effect)`.**
    Give the Worker's `scheduled` and `queue` handlers as
    `routes.scheduled((event) => effect)` and
    `routes.queue(MessageSchema, (message) => effect)`, which run the work with
    the application's services, never through a hidden route; test them with
    `testBatch` and `testEnv`.
11. **Give `cache: 'private'` to routes whose page reads something the framework
    cannot see,** such as an external `fetch()` or the current time, and
    `cache: 'no-store'` to one no cache may keep, such as a signed preview. Pages that
    read bindings, headers or bound models are already rendered per request.
    A route that changes records cached pages show purges them with
    `purges: true`, and an action adds other records it changed with
    `purgeCache(recordCacheTag('listings', id))`. Give data kept with
    `cache(key, effect, schema, { ttl, tags })` the same tags, so the same
    purges invalidate it. An API that authenticates each request (a bearer
    token) caches its data this way, after authenticating, never its
    response.
12. **Test through the app.** `app.request(path, init, testEnv(layer,
    bindings))` from `@popcomputer/web/testing` runs the real route;
    `signedIn(row)` signs the request in (pass the seeded user row when the
    user table has columns of its own), `testBrowser(app, env)` carries a
    visitor's cookies across requests, and `readPage(res, 'Name')` reads
    an `X-Inertia` response typed by the page registry. Test against the
    production database family: PGlite for Postgres (`testEnv`'s `database`),
    migrated with `applyMigrations`, and for D1 a database of each test's own
    from `testD1({ migrations: './migrations' })`, the folder wrangler applies, stopped by
    `afterAll(() => databases.dispose())` in `bunfig.toml`'s preload. Replace a service
    that reaches another system with `Layer.succeed(Service, fake)` in the
    layer, wherever the application gives that service (`web.services` or
    `routes.provide`), stand in for an OAuth provider with `testOAuthProvider({ ... })`
    and sign people in through it with `signIn(browser, path, person)`, and move time with `testClock()`, which works when rules read the
    time through Effect's `Clock` or `DateTime.now`; `time.settle(request)`
    runs a request whose retries wait on the clock. A new test must fail
    when the behaviour it covers is reverted: plant the bug first (undo the
    fix, or break the rule), watch the test fail, then restore the code. A
    test that passes either way checks nothing. Fuzz the application's
    routes with `fuzzRequest({ paths, params, people, forms })` from
    `@popcomputer/web/fuzz`, sending each request with `sendFuzzRequest`
    and checking its answer with `brokenPromises`, `leaks`, `strangerWrites`
    and `refusedWrites`, as `docs/fuzzing.md` shows, and add the
    application's own rules beside them; give each new action a form there,
    and each new placeholder its values. Check any other rule on generated
    inputs with `fuzz(arbitrary, holds)`.
13. **Declare every JSON endpoint once, as a contract,** in `src/endpoints.ts`:
    `endpoint.post(paths.apiProjects, { body, success, status: 201, errors:
    { 409: SlugTaken } })` from `@popcomputer/web/endpoint`, with `query`,
    `body` and `headers` schemas for its input, `success` for its body and
    each failure a client tells apart as an `S.TaggedError` under its status.
    Declare a JSON number with Effect's schemas (`S.Int.check(S.isGreaterThan(0))`),
    not the form validators, which accept `"12"` for a form's sake.
    Give it `auth: true` when it needs a signed-in user, which the handler
    then receives as `auth`, rather than calling `authorize()` in it.
    Implement it with `action(endpoints.createProject, ({ auth, params, body }) =>
    Effect.gen(...))`, which receives the input decoded and returns the
    success value, and register it with `routes.endpoint(createProject)`,
    which takes the method and path from the contract. Do not call
    `validateRequest` or `json` in it. Test it with `call(endpoints.x, input,
    { fetch: (request) => app.request(request, undefined, env) })`, and
    publish `openApi(endpoints, { title, version, security })`. Pages' forms stay ordinary actions.

Every name has one entrypoint: `@popcomputer/web` for `setupWeb`, template
helpers and Hono middleware; `@popcomputer/web/effect` for actions, routes,
responses, pages, the database, services and errors;
`@popcomputer/web/schema` for validators; `@popcomputer/web/auth` for the
Better Auth integration; `@popcomputer/web/cache` for the KV cache;
`@popcomputer/web/drizzle` for `rowOf`; `@popcomputer/web/endpoint` for
`endpoint`, `call` and `openApi`, on the server and in clients alike;
`@popcomputer/web/env` for `defineEnv`, `secret`, `variable` and
`checkEnv`, in the Worker and in scripts alike;
`@popcomputer/web/lint` for `webLint`, in `oxlint.config.ts`;
`@popcomputer/web/vite` for `reloadWorkerModules`, in `vite.config.ts`;
`@popcomputer/web/fence` for `commandPolicy` and `disableDirectives`,
behind the `popweb-fence` command an agent's hook and the commit gate run;
`@popcomputer/web/react` for page component types; `@popcomputer/web/paths`
for `href`, in React and actions alike; `@popcomputer/web/testing` in tests;
`@popcomputer/web/fuzz` for `fuzz`, `fuzzRequest` and the rules answers keep,
in tests.

## A complete action

```ts
// src/actions/projects/update.ts
import { eq } from 'drizzle-orm'
import { Effect, Schema as S } from 'effect'
import { action, bound, dbMutation, flash, redirect, validateRequest } from '@popcomputer/web/effect'
import { nullableString, requiredString } from '@popcomputer/web/schema'
import { paths } from '../../paths'
import { projects } from '../../schema'

const UpdateProject = S.Struct({
  name: requiredString,
  description: nullableString,
})

export const updateProject = action(
  Effect.gen(function* () {
    // Its owner's only: the binding is ownedBy 'userId'.
    const project = yield* bound('project')
    const input = yield* validateRequest(UpdateProject)

    yield* dbMutation((db) =>
      db.update(projects).set(input).where(eq(projects.id, project.id))
    )
    yield* flash('success', 'Project saved.')

    return yield* redirect(paths.project, { project: project.id })
  })
)
```

Register it beside the other routes in `src/routes.ts`:

```ts
routes.put(paths.project, updateProject, { name: 'projects.update' })
```

Test it as `docs/testing.md` shows: request
`PUT /projects/project-1` with `testEnv(signedIn({ id: 'user-1' }),
testBindings)` and expect a `303` to `/projects/project-1`, a `404` for
another user, and, for an empty name, a `303` back to the form whose next page
has `errors.name` (a JSON request gets a `422`).

## Do not use

- `c.req.json()`, `c.req.parseBody()` or `c.env` inside actions.
- `DatabaseService` or raw `db` calls outside `dbQuery`, `dbMutation`,
  `dbTransaction` and `dbBatch`.
- `app.get(...)` or other routes on the Hono app; register on `routes`.
- Names from the old `honertia` package (`setupHonertia`, `HonertiaService`,
  `c.var.honertia`, ...): `UPGRADING.md`'s table lists their
  replacements.

## Before finishing

Run the application's type check (`tsc --noEmit`), the package's lint rules
(`bunx oxlint`, with `oxlint.config.ts` exporting
`defineConfig(webLint())` from `@popcomputer/web/lint`) and `bun test`. Let
the type check run the Effect language service, whose `floatingEffect` fails
it on any Effect neither yielded nor assigned, where the lint rule sees only
the framework's calls: `bun add -d @effect/tsgo`, `"plugins": [{ "name":
"@effect/language-service" }]` in `tsconfig.json`'s `compilerOptions`, and
`"prepare": "effect-tsgo patch"` in `package.json`, since `tsc` ignores the
plugin until it is patched (`docs/lint-rules.md` has the details). Each
lint message names the API to use instead; fix the code rather than
disabling the rule, and when a line breaks one on purpose, say why in the
disable comment. A type error
at `routes.get(...)` names the problem: `missingServices` lists services the
setup does not provide (configure them in `setupWeb`, or `routes.provide(layer)`),
`unhandledErrors` lists failures that are not the package's errors (answer
them with `Effect.catchTag`, or pipe a call whose failure the action cannot
answer through `Effect.orDie`; `"noErrorTruncation": true` in `tsconfig.json`
shows every one), and
`missingRouteModels` lists models the action or a provided guard reads with
`bound()` that the route's path does not bind. A type error at
`render(...)` means the page or its props differ from `src/pages.ts`.
`Argument of type 'string' is not assignable to parameter of type 'readonly
[never, ...never[]]'` at an `Effect.catchTag` means the Effect no longer fails
with that tag: remove the handler. The same error, or `... | { readonly _tag:
unknown }` is not assignable, at a `catchTag` written apart from an Effect,
as a reusable helper, means TypeScript cannot see the errors it handles:
write it inside `.pipe(...)`, or use `Effect.mapError` with an `instanceof`
check (`Effect.catchIf((error) => error instanceof X, ...)` when the error
type is a type parameter). `not assignable to type '{ EntitlementRequired: never; }'` at an
`Effect.catchTags` means the same of that tag: remove its handler. A registration, `routes.run` or an
`action(...)` reporting an `Effect<..., unknown, unknown>`, or
`missingServices: "unnamed service"`, means an earlier type error in the
action made its types unknown: fix that one first.
`'web' implicitly has type 'any'` (TS7022) means a value in `setupWeb`'s
configuration has a type that reads the registration, such as one using
`dbQuery`: give services to `web.services(...)`, after the registration, as
rule 9 shows.
Many errors naming `DatabaseNotConfigured`, or `(c) => never` at `database`,
while `setupWeb` has a database factory, mean one value in its configuration
has a type error, such as a page schema using a deleted import: TypeScript
then infers none of the configuration's types. Fix the first error inside the
`setupWeb` call.

## The fence

The rules that matter most are also checks, which `docs/agent-fence.md`
sets up: the commit gate runs the type check, the lint rules, the tests and
`popweb-fence debt --check` before every commit, and the agent's command
hook refuses a command that skips the gate and asks the owner before one
that needs them. When an enforced check and a paragraph disagree, the check
wins: follow it, and fix the paragraph. When a check fails, fix what it
reports; never skip the gate (`git commit --no-verify`, `-n`, `HUSKY=0`, a
changed `core.hooksPath`) or loosen a check to get a green result. The debt
report counts every comment that turns a rule off, and the count only
shrinks: `popweb-fence debt --update` records a lower count, and only the
owner raises it. When a bad pattern recurs, add the lint rule that reports
it before cleaning it up, so the cleanup cannot come undone: in the
application's `oxlint.config.ts` for its own code, in `webLint` for a
mistake any application could make.

## Boundaries and sign-off

What an agent may change alone, and what needs the owner. Copy this section
into the application's own `AGENTS.md` and add the application's own
steps; until then, these hold.

- **An agent may, alone:** write and change actions, routes, pages,
  services, schemas, migrations and their tests; run them against the local
  database (`wrangler d1 migrations apply --local`, `wrangler dev`) and
  build with `wrangler deploy --dry-run`; add or tighten a test, a lint rule
  or a binding's access; fix the code a rule reports, lowering the debt;
  edit the documentation and `AGENTS.md`, except this section; commit
  locally once the gate passes.
- **Needs the owner's sign-off:** a deploy (`wrangler deploy`, `wrangler
  versions deploy`, `wrangler rollback`); remote D1 migrations, and any
  other `--remote` read or write; secrets (`wrangler secret put`);
  publishing a package; a push; loosening `oxlint.config.ts` or a
  `webLint` severity, or raising the debt count; changing the commit gate
  or the agent's hooks; and widening access: who may load a record (a
  binding moved from `ownedBy` to `publicWhen`, `public` or `guarded`), the
  user fields `betterAuthHandler`'s `settable` names, `verifyOrigin`'s
  `allowedOrigins`, a raised `bodyLimit`, or `history.encrypt` turned off.

The command hook asks the owner before the steps it can see. Ask before the
others yourself, and say what the change widens.

---

<!-- docs/which-api.md -->

# Which API for which task

Each task has one API. When the one you need is not here, the type checker
and the lint rules name it where an action reaches for something else.

**Requests and responses**

| Task | Use | See |
| --- | --- | --- |
| Read form, query or JSON input | `validateRequest(Schema)` | [Validating input](validation.md) |
| Read a header, or the raw body a webhook signs | `RequestService`'s `header(name)` and `raw()` | [Webhooks](webhooks.md) |
| Accept a file | `upload({ types, maxBytes })` in the schema, and `validateRequest`'s `bodyLimit` past 1 MiB | [User input in](validation.md#user-input-in) |
| Render a page | `render('Projects/Show', props)` | [Actions and routes](actions.md) |
| Redirect after a write | `redirect(paths.project, { project: id })` | [Responses](actions.md#responses-and-failures) |
| Go back to the page the request came from | `back(paths.projects)` | [Responses](actions.md#responses-and-failures) |
| Send the visitor elsewhere from a helper or a guard | `redirectNow(paths.onboarding)` | [Responses](actions.md#responses-and-failures) |
| Show a domain error beside a form field | `invalid({ amount: 'Too low.' })` | [Rules live in services](services.md#rules-live-in-services-actions-decide-what-a-failure-means) |
| Hand a message to the next page | `flash('success', 'Saved.')` | [Flash and failed forms](forms.md#flash-messages-and-failed-forms) |
| Answer a JSON API | an `endpoint` contract, implemented with `action(endpoint, handler)` | [JSON endpoints](endpoints.md) |
| Answer JSON from a page's action | `json(Schema, value)` or `jsonOrRender('Page', props)` | [JSON responses](json.md#json-responses-declared-by-a-schema) |
| Answer a failure with a body a client reads | `httpError(status, message, Schema, body)` | [Failures a client reads](json.md#failures-a-client-reads) |
| Hide a record the visitor may not see | Its binding's `ownedBy` or `publicWhen`, or `notFound('Project')` in a guard | [Who may load a record](route-models.md#who-may-load-a-record) |
| Refuse a visitor who can see the record | `authorize((auth) => rule)`, or `forbidden(message)` | [Auth](auth.md) |
| Serve a file or a download | `file(body, { contentType, filename })` | [Serving an upload back](responses.md#serving-an-upload-back) |
| Answer a poll that has nothing new | `ifChanged(etag, response)` | [Files, headers and polling](responses.md#files-headers-and-polling) |
| Add a header to every response of some routes | `responseHeader(name, value)` in a guard layer | [Files, headers and polling](responses.md#files-headers-and-polling) |
| Keep a value in the visitor's browser | `cookie(name, Schema, options)`, declared once | [Cookies](responses.md#cookies) |
| Answer a CORS preflight | `routes.options(path, action(noContent(headers)))` | [Files, headers and polling](responses.md#files-headers-and-polling) |

**Routes, models and pages**

| Task | Use | See |
| --- | --- | --- |
| Declare a URL, and build links to it | `paths` in `src/paths.ts`, `href(paths.project, params)` | [Actions and routes](actions.md) |
| Load the record a URL names | `bindings: { project: routeBinding(schema.projects, { ownedBy: 'userId' }) }`, then `bound('project')` | [Route model binding](route-models.md) |
| Say who may load it | `ownedBy: 'userId'` for its owner, `publicWhen: { isPublic: true }`, `public: true`, or `guarded: true` when a guard decides | [Who may load a record](route-models.md#who-may-load-a-record) |
| Guard a group of routes | `routes.provide(guard(effect))`, or `RequireAuthLayer` | [A guard guards a group of routes](guards.md#a-guard-guards-a-group-of-routes) |
| Check a role or a permission | `yield* can('members.role')` in the action, after a membership `guard(CurrentMember, ...)` | [Roles belong to memberships](guards.md#roles-belong-to-memberships-read-by-a-guard) |
| Show the same props on every page | `shared` in `setupWeb`, computed by `shareProps(effect)` | [Props every page shows](pages.md#props-every-page-shows) |
| Declare a page's props | a schema in `src/pages.ts`, typed in React as `WebPage<'Name'>` | [Describe the pages](pages.md#describe-the-pages) |
| Take a page's fields from a table | `tableSchema(table).mapFields(Struct.pick([...]))` | [Describe the pages](pages.md#describe-the-pages) |
| Type a form | `useForm<FormInput<typeof Schema>>`, `FormErrors<typeof Schema>` | [Forms](forms.md) |
| Type the error page | `WebErrorPage` | [The error page](pages.md#the-error-page) |
| Edit routes and actions while Vite's dev server runs the Worker | `reloadWorkerModules()` from `@popcomputer/web/vite` in `vite.config.ts`'s plugins | [Installation](installation.md) |

**Auth**

| Task | Use | See |
| --- | --- | --- |
| Require a signed-in user | `authorize()` | [Auth](auth.md) |
| Read the user when signing in is optional | `currentUser` | [Auth](auth.md) |
| Sign in or sign up | `validateRequest`, then `betterAuthRedirect('signInEmail', { body }, { redirectTo, errors })` | [Signing in and out](sign-in.md) |
| Return to the page the visitor wanted | `intendedUrl(fallback)` | [Signing in and out](sign-in.md) |
| Call Better Auth for a result | `betterAuthCall('enableTwoFactor', { body }, { errors })` | [Signing in and out](sign-in.md) |
| Sign out | `betterAuthLogoutAction({ redirectTo, clear })` | [Signing in and out](sign-in.md) |
| Limit password guessing | `auth.signInLimits`, `sweepSignInFailures` | [Limiting password guessing](auth.md#limiting-password-guessing) |
| Use a Better Auth plugin: organizations, two-factor, magic links | its endpoints by name with `betterAuthRedirect` and `betterAuthCall` | [Better Auth's plugins](auth-plugins.md) |
| Sign in through an OAuth provider, a company's own or GitHub's | `betterAuthRedirect('signInSocial', ...)`, and `betterAuthHandler()` on the callback alone | [Signing in with an OAuth provider](auth-plugins.md#signing-in-with-an-oauth-provider) |
| Add a field to the user | a column on the user table, with `betterAuthFields` | [Auth](auth.md) |
| Authenticate an API key | a layer failing with `new UnauthorizedError({ message, challenge: 'Bearer' })` | [Caching an API](data-cache.md#caching-an-api-that-authenticates-each-request) |

**The database**

| Task | Use | See |
| --- | --- | --- |
| Read | `dbQuery((db) => ...)` | [The database](database.md) |
| Write | `dbMutation((db) => ...)` | [The database](database.md) |
| Write several things together (Postgres, MySQL, libsql) | `dbTransaction(Effect.gen(...))` | [The database](database.md) |
| Write several things together on Cloudflare D1 | `dbBatch((db) => [...])` | [Constraints](constraints.md) |
| Insert only while a condition holds, on D1 | `db.insert(table).select(db.select(rowOf(table, values))...)` | [Constraints](constraints.md) |
| Keep a rule concurrent requests could break | a constraint (`CHECK`, unique, exclusion, trigger) | [Constraints](constraints.md) |
| Show a duplicate beside its field | `uniqueFieldErrors({ slug: 'Taken.' })` | [The database](database.md) |
| Show a named rule beside its fields | `constraintFieldErrors({ name: { field: message } })` | [Constraints](constraints.md) |
| Select exactly the columns a page shows | `columnsOf(table, Schema)` | [Describe the pages](pages.md#describe-the-pages) |

**Services, background work and caching**

| Task | Use | See |
| --- | --- | --- |
| Provide a service | `web.services({ app, request })`, after registering `web` | [Application services](services.md) |
| Declare the Worker's vars and secrets | `defineEnv` with `secret(schema, { generate })` and `variable(schema)`, passed as `setupWeb`'s `env` | [Vars and secrets](env.md) |
| Check vars and secrets in a script, before a deploy | `checkEnv(env, values)` | [Vars and secrets](env.md#checking-them-before-a-deploy) |
| Read a var or a secret | `config.string('NAME')`, `config.redacted('KEY')` | [Application services](services.md) |
| Work after the response | `background('name', effect)` | [Work after the response](background.md#work-after-the-response) |
| Run a Cron Trigger or a Queue consumer | `routes.scheduled(job)`, `routes.queue(Schema, handle)` | [Scheduled and queued work](background.md#scheduled-and-queued-work) |
| Cache computed data | `cache(key, effect, Schema, { ttl, tags })`, with `kvCache` in `web.services` | [The data cache](data-cache.md) |
| Cache a public page for a time | the route's `cache` option | [Workers Cache](page-cache.md#time-based-caching-with-workers-cache) |
| Refresh cached pages and data after a write | `purges: true`, `purgeCache(recordCacheTag(table, id))` | [Workers Cache](page-cache.md#time-based-caching-with-workers-cache) |
| Tag a cached page with records it read | `tagCache(recordCacheTag(table, id))` | [Workers Cache](page-cache.md#time-based-caching-with-workers-cache) |

**Testing**

| Task | Use | See |
| --- | --- | --- |
| Run a request through the application | `app.request(path, init, testEnv(layer, bindings, { database }))` | [Testing](testing.md) |
| Sign a request in | `signedIn(user)` in `testEnv`'s layer | [Testing](testing.md) |
| Read a page, JSON, a failure or a cookie | `readPage`, `readJson`, `readError`, `readErrorPage`, `readCookie` | [Reading a response](testing.md#reading-a-response) |
| Make several requests as one visitor, or follow a redirect | `testBrowser(app, env)` and its `follow(res)` | [One visitor](testing.md#one-visitor-across-requests) |
| Replace a service that reaches another system | `Layer.succeed(Service, fake)` in `testEnv`'s layer | [Fakes](testing.md#fakes-for-other-systems) |
| Move time | `testClock()` | [Time](testing.md#time) |
| Use the production database family | PGlite, migrated with `applyMigrations`, or a D1 database of each test's own from `testD1` | [A database for tests](test-database.md) |
| Check a rule on generated inputs | `fuzz(arbitrary, holds)` from `@popcomputer/web/fuzz` | [Fuzzing](fuzzing.md) |
| Fuzz the application's routes | `fuzzRequest({ paths, params, people, forms })`, `sendFuzzRequest`, and `brokenPromises`, `leaks`, `strangerWrites`, `refusedWrites` | [Requests to the application](fuzzing.md#requests-to-the-application) |
| Sign in through an OAuth provider in a test | `testOAuthProvider({ ... })`, then `signIn(browser, path, person)` | [Signing in with an OAuth provider](auth-plugins.md#signing-in-with-an-oauth-provider) |
| Run a Queue consumer | `testBatch(bodies)` | [Scheduled and queued work](background.md#scheduled-and-queued-work) |

**The agent fence**

| Task | Use | See |
| --- | --- | --- |
| Run the checks before every commit | `.githooks/pre-commit`, installed with `git config core.hooksPath .githooks` | [The commit gate](agent-fence.md#the-commit-gate) |
| Refuse a command that skips the gate, and ask the owner before a deploy | `popweb-fence hook` in `.claude/settings.json` or `.cursor/hooks.json` | [The command hook](agent-fence.md#the-command-hook) |
| Check a command or an edit from an agent's own code | `commandPolicy(command, { scripts })`, `filePolicy(path)` | [Other agents](agent-fence.md#other-agents) |
| List every disable directive, and keep the count from rising | `popweb-fence debt`, and `--check` against `lint-debt.json` | [The debt report](agent-fence.md#the-debt-report) |

---

<!-- docs/type-errors.md -->

# Reading the type errors

The framework reports most mistakes as type errors where they are made, and
each names what is wrong. Fix the first error in a file before reading the
rest: one error inside an action or `setupWeb`'s configuration can make
TypeScript give up on the types that later errors are about.

| Where, and what it says | What it means | What to do |
| --- | --- | --- |
| A registration, `missingServices: "@popcomputer/web/Database"` | The action uses a service the setup does not provide | Configure it in `setupWeb` (`database`, `auth.client`, `services`), or `routes.provide(layer)` |
| A registration, `unhandledErrors: "PaymentDeclined"` | The action can fail with an error the boundary cannot answer | Turn it into a response with `Effect.catchTag`: `invalid`, `notFound`, `httpError`, `flash` then `back`. A failure the action cannot answer, such as another system being down: pipe that call through `Effect.orDie`, which answers 500. A list cut off with `... 7 more ...` shows whole with `"noErrorTruncation": true` in `tsconfig.json` |
| A registration, `missingRouteModels: "project"` | The action, or a guard it is registered under, calls `bound('project')`, and the path has no `{project}` | Register it on a path with the placeholder, or read the record by an id from `validateRequest` |
| A registration or `action(...)`, `Effect<..., unknown, unknown>` or `missingServices: "unnamed service"` | An earlier type error inside the action made its type unknown | Fix the first error inside the action |
| `render(...)`, props not assignable | The page's name or props differ from `src/pages.ts` | Change the props, or the page's schema |
| A path literal, `Not one of setupWeb's paths`, with `declaredPaths` | The path is not declared | Declare it in `src/paths.ts` and pass `paths.x` |
| `bound('...')`, `config.string('...')`, a key not assignable | A misspelled binding, or a var the bindings type does not declare | Use a name the error lists, or declare it in `src/env.ts`'s `defineEnv` |
| `Effect.catchTag('X', ...)`, `not assignable to parameter of type 'readonly [never, ...never[]]'` | The Effect no longer fails with `X` | Remove the handler |
| `Effect.catchTags({ X: ... })`, `not assignable to type '{ X: never; }'` | The same, for one of the handlers | Remove that handler |
| A `catchTag` in a helper written apart from its Effect, `{ readonly _tag: unknown }` not assignable | TypeScript cannot see the errors the helper handles | Write it inside `.pipe(...)`, or use `Effect.catchIf((error) => error instanceof X, ...)` |
| `routeBinding(table, { ... })`, `No overload matches this call`, naming `Codec` | TypeScript reports the last overload, the one for an Effect Schema, though the options are what's wrong: two of `ownedBy`, `public`, `publicWhen` and `guarded`, a column the table lacks, or a `publicWhen` value of another type than its column's | Give one option, naming the table's columns by their property keys, with values of their columns' types, as `{ publicWhen: { visibility: 'public' } }` |
| `setupWeb(...)` given `services` | Services are given after the registration | Move them to `export const { app, routes } = web.services({ app, request })`, after the `Register` declaration |
| Inside `setupWeb(...)`, many errors naming `DatabaseNotConfigured`, or `(c) => never` at `database` | One value in the configuration has a type error, so TypeScript infers none of its types | Fix the first error inside the `setupWeb` call |
| A database result, `This result's type is any` | The driver's types name Cloudflare's global types, which the program cannot find | Add `@cloudflare/workers-types`, or the file `wrangler types` writes, to `compilerOptions.types` |
| `dbTransaction(...)`, `Use dbBatch for atomic writes, or a driver with transactions.` | The database has no interactive transactions: Cloudflare D1, or a synchronous driver such as `bun:sqlite` | Write the statements as one `dbBatch` |
| A `dbBatch` on D1, `Drizzle cannot run db.run(sql) with parameters in a Cloudflare D1 batch` | Drizzle's D1 batch fails at runtime on a raw statement | Write the statement with the query builder |

What types cannot see, such as an update without a `where` or a network call
inside a transaction, the [lint rules](lint-rules.md) report.

---

<!-- docs/actions.md -->

# Actions and routes

Each route's path is declared once, and every URL to it is built from that
declaration: the route registration, a server redirect and a client link. The
module holds only data, so server and React code both import it, and
`setupWeb`'s `paths` takes it, so `routes` registers only on declared paths,
and a path literal given to `redirect`, `back`, `href` or `intendedUrl` must
be one of them or an absolute URL: a misspelled path is a type error. A URL
computed at runtime, such as one `href` built, is a string and passes.

```ts
// src/paths.ts
export const paths = {
  login: '/login',
  logout: '/logout',
  verifyEmail: '/verify-email',
  authApi: '/api/auth/*',
  authCallback: '/api/auth/callback/{provider}',
  loginWithAcme: '/login/acme',
  dashboard: '/dashboard',
  billing: '/billing',
  pricing: '/pricing',
  explore: '/explore',
  projects: '/projects',
  project: '/projects/{project}',
  projectName: '/projects/{project}/name',
  projectBySlug: '/p/{showcase:slug}',
  organizationMembers: '/orgs/{organization:slug}/members',
  organizationMember: '/orgs/{organization:slug}/members/{member:userId}',
  task: '/projects/{project}/tasks/{task}',
  apiProjects: '/api/projects',
  apiProject: '/api/projects/{project}',
  apiDescription: '/api/openapi.json',
} as const
```

```ts
// src/actions/projects/show.ts
import { Effect } from 'effect'
import { action, bound, render } from '@popcomputer/web/effect'

export const showProject = action(
  Effect.gen(function* () {
    // The binding is ownedBy 'userId': another member's project answers 404,
    // as a missing one does, so its existence stays private.
    const project = yield* bound('project')

    return yield* render('Projects/Show', { project })
  })
)
```

```ts
// src/routes.ts
import { routes } from './app'
import { paths } from './paths'
import { showProject } from './actions/projects/show'

routes.get(paths.project, showProject, { name: 'projects.show' })
```

`redirect(paths.project, { project: project.id })` and, in React,
`href(paths.project, { project: project.id })` from `@popcomputer/web/paths` fill
the path's placeholders; the parameters are typed from them, so a renamed
placeholder is a type error at every URL built from it. A value fills one path
segment: an empty one, `.` or `..` would turn the path into another route's,
or `//host`, another site, and a URL reads `%2e` as a dot, so no escape keeps
one, and no URL can carry text with a lone surrogate, which a JSON body can hold.
`href` and `redirect` leave such a placeholder unfilled, as a missing
value, `/orgs/{organization}`: the link stays on its route and site, and one
stored slug of `..` breaks only its own link, never a page or job listing
others. An endpoint's `call` throws on it. Validate a name a URL will carry
with `alphaDash`, as for a slug, which also refuses `{` and `}`. A redirect leads to a
path or an `http:` or `https:` URL: one to any other scheme, such as a
`javascript:` URL a form's `next` field names, is a defect that answers 500,
and an Inertia visit is sent to another site only at an `http:` or `https:`
URL. Take the page to return to from `intendedUrl`, which returns only a path
on this site.

`routes` accepts an action only when the setup provides every service the
action uses and the action fails only with the package's errors. Otherwise the
registration is a type error that names the problem, for example
`missingServices: "@popcomputer/web/Database"` when no `database` is
configured, `unhandledErrors: "PaymentDeclined"` for a domain error the
action has not handled, or `missingRouteModels: "project"` for an action that
calls `bound('project')` on a path without `{project}`. `routes.provide(layer)`
adds services for the routes registered through it.

Routes that share a path prefix and a guard are grouped with
`routes.prefix(...)`. The prefix's placeholders bind models for every route
under it, so a guard layer provided on the group reads them with `bound()`,
and each route under it is registered with its whole declared path. A path
under a prefix that is not declared, or does not start with it, is a type
error. [Roles belong to memberships](guards.md#roles-belong-to-memberships-read-by-a-guard)
groups an organization's routes this way.

`action` does not hide another execution model. It preserves the Effect's
success, error, and requirement channels, while documenting that the program is
an HTTP action.

## Responses and failures

Choose the helper that matches the current action branch. These are alternative
endings, not statements to run in sequence:

| Intent | Action ending |
|---|---|
| Render a page | `return yield* render('Dashboard', { stats })` |
| Redirect | `return yield* redirect(paths.project, { project: project.id })` |
| Redirect to the page the request came from | `return yield* back(paths.project, { project: project.id })`, falling back to that path |
| Redirect from a helper or guard layer, ending the action | `yield* redirectNow(paths.dashboard)` |
| Return JSON declared by a schema, encoded as page props are | `return yield* json(ProjectList, { projects })` |
| Return JSON no client decodes, such as a webhook's acknowledgement | `return yield* json({ received: true })` |
| Return JSON when requested, otherwise render a page | `return yield* jsonOrRender('Projects/Index', { projects })` |
| Fail with `NotFoundError` | `return yield* notFound('Project', projectId)` |
| Fail with `ForbiddenError` | `return yield* forbidden('You cannot edit this project')` |
| Send a form back with field errors | `return yield* invalid({ name: 'That name is taken.' })` |
| Render a page that reports a failure, with its status | `return yield* render('Signing/LinkInvalid', {}, { status: 404 })` |
| Answer 500 for a failure the action cannot answer | `yield* crm.export(project.id).pipe(Effect.orDie)` |

Flash messages and a failed form's errors are in [Forms](forms.md#flash-messages-and-failed-forms);
cookies, files and headers in [Cookies, files and headers](responses.md);
JSON responses and the failures a client reads in [JSON clients](json.md).

## Failures an action cannot answer

Some failures have no answer the action can give: another system is down, a
storage write failed. They are defects. Pipe the call that fails through
`Effect.orDie`, and the request answers 500, with a generic message in
production and the failure's tag on the development error page, and the error
observer receives the failure itself, as `kind: 'defect'`:

```ts
class CrmUnavailable extends S.TaggedError<CrmUnavailable>()('CrmUnavailable', {}) {}

/** Another system the application hands its projects to. */
declare const crm: { readonly export: (projectId: string) => Effect.Effect<void, CrmUnavailable> }

const exportProject = action(Effect.gen(function* () {
  yield* authorize()
  const project = yield* bound('project')

  yield* crm.export(project.id).pipe(Effect.orDie)

  return yield* redirect(paths.project, { project: project.id })
}))
```

Never pipe `authorize()`, `bound()`, `validateRequest` or a database call
through `Effect.orDie`: their failures are answers, a redirect to sign in, a
404 or the form's errors, and the `no-catch-all-in-action` lint rule reports
it.

## Reporting failures

Typed failures, defects, Hono exceptions, and not-found responses share the
configured error boundary. Use `EffectErrorObserverService` as the integration
point for Sentry, PostHog, or another reporting system; observation does not
change the failure channel. It receives every failure, a form's 422 included:
a failed validation carries each field's message, path and code but never the
value sent, which can be a password, a cookie or a token. Its context names
the route, the URL's origin, route pattern and query names, and the Referer's
origin, never a value a URL carries, such as a reset link's token.

---

<!-- docs/agent-fence.md -->

# The agent fence

`AGENTS.md` asks an agent to run the type check, the lint rules and the
tests, to say why it turns a rule off, and to leave deploys to the owner. An
agent can skip a paragraph; it cannot skip a check that refuses to pass. The
fence turns those rules into three checks:

- the commit gate runs the checks before every commit;
- the agent's command hook refuses a command that skips the gate, and asks
  the owner before one that deploys, touches remote data, changes secrets,
  publishes or pushes;
- the debt report counts every comment that turns a rule off, so the count
  only shrinks.

When an enforced check and a paragraph disagree, the check wins and the
paragraph gets fixed. The checks ship in the package as the `popweb-fence`
command and the `@popcomputer/web/fence` entrypoint, which import only
Node's built-ins.

## The commit gate

The gate is the checks `AGENTS.md`'s "Before finishing" names, as a git
pre-commit hook. Commit it as `.githooks/pre-commit`:

```sh
#!/bin/sh
# The commit gate: the checks an agent runs before finishing, before every commit.
set -e
bunx tsc --noEmit
bunx oxlint
bun test
bunx popweb-fence debt --check
```

Install it once, in your own terminal:

```bash
chmod +x .githooks/pre-commit && git config core.hooksPath .githooks
```

The command hook refuses an agent's `git config core.hooksPath`, so the
owner installs the gate, and every worktree of the repository shares it. A
team on [Lefthook](https://lefthook.dev) commits the same checks as
`lefthook.yml` instead, and runs `bunx lefthook install`:

```yaml
pre-commit:
  parallel: false
  commands:
    types:
      run: bunx tsc --noEmit
    lint:
      run: bunx oxlint
    test:
      run: bun test
    debt:
      run: bunx popweb-fence debt --check
```

When the gate fails, fix what it reports and commit again. `git commit
--no-verify`, `git commit -n`, `HUSKY=0`, `LEFTHOOK=0` and a changed
`core.hooksPath` all skip it, and the command hook refuses each one.

## The command hook

`popweb-fence hook` reads the command an agent is about to run, as the
agent's hook passes it, and answers in that agent's format.

| It finds | For example | It |
| --- | --- | --- |
| A way around the commit gate | `git commit --no-verify`, `-n`, `HUSKY=0`, `LEFTHOOK=0`, `-c core.hooksPath=...`, `lefthook uninstall`, a write into `.git/hooks/` | refuses it |
| A deploy | `wrangler deploy`, `wrangler versions deploy`, `wrangler rollback` | asks the owner |
| Remote data | `wrangler d1 migrations apply --remote`, `wrangler d1 execute --remote`, any `wrangler ... --remote` | asks the owner |
| A secret | `wrangler secret put`, `bulk` or `delete` | asks the owner |
| A release | `npm publish`, `bun publish`, `pnpm publish` | asks the owner |
| A push | `git push` | asks the owner |
| A change to the fence | `oxlint.config.ts`, `lefthook.yml`, `.githooks/`, `.claude/settings.json`, `lint-debt.json`, `popweb-fence debt --allow-increase` | asks the owner |

`wrangler deploy --dry-run`, `npm publish --dry-run`, `git push --dry-run`
and D1's local database (`--local`, the default) need no one.

The hook reads a command line as the shell would: through quotes and
escapes, `&&`, `||`, `;` and pipes, `sh -c` and `bash -lc`, `eval`,
`$(...)`, heredocs, env prefixes and `env`, `npx`, `bunx`, `pnpm exec` and
`node_modules/.bin`, the variables the line sets itself, and the
`package.json` scripts a runner names, so `bun run deploy` asks when its
script deploys. It also reads a shell script the command runs, and the
strings of a JavaScript or TypeScript one.

### Claude Code

Commit `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bun \"$CLAUDE_PROJECT_DIR/node_modules/@popcomputer/web/dist/fence/cli.js\" hook"
          }
        ]
      }
    ]
  }
}
```

Claude Code shows a refusal's reason to the agent. It puts a question to
you in its permission prompt, auto mode included: approve the one command,
or decline it and run it yourself. In a `claude -p` run, where nobody can
answer, it refuses the command. The `Edit` and
`Write` matchers send file edits through the same policy, so an edit of
`.git/hooks/` is refused and an edit of a fence file asks. `node` runs the
hook as well as `bun`.

### Cursor

Commit `.cursor/hooks.json`; a project's hooks run from its root:

```json
{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "bun node_modules/@popcomputer/web/dist/fence/cli.js hook",
        "failClosed": true
      }
    ]
  }
}
```

`failClosed` refuses a command when the hook itself fails, and until `bun
install` has run, it fails: run the first install yourself. Claude Code has
no such setting and lets the command through.

### Other agents

An agent whose hook pipes the command line to a program and blocks on exit
status 2 uses the command as it is: `popweb-fence hook` reads a plain command
line on stdin, and exits 2 with the reason on stderr when the command must
not run. Check it by hand:

```bash
echo 'sh -c "git commit --no-verify"' | bunx popweb-fence hook
```

An agent whose hooks are code, such as a Pi extension, calls the policy
itself:

```ts
// scripts/agent-policy.ts
import { readFileSync } from 'node:fs'
import { commandPolicy, filePolicy } from '@popcomputer/web/fence'

const { scripts } = JSON.parse(readFileSync('package.json', 'utf8')) as { scripts?: Record<string, string> }

export const beforeCommand = (command: string) => commandPolicy(command, { scripts })
export const beforeEdit = (path: string) => filePolicy(path)
```

Each returns `{ decision: 'allow' }`, or a `decision` of `'deny'` or `'ask'`
with the `rule`, the `subject` and the `reason`.

### What it cannot see

The hook reads the command line, not the system it runs on. It cannot see a
git alias or a shell alias set outside the line, a `make` or `just` target,
a program in another language, or a command a program builds at run time.
When a spelling gets past it, add the case to the policy's tests before
anything else, as the gardener rule in `AGENTS.md` says.

## The debt report

`popweb-fence debt` lists every comment in the application's source that
turns a rule or a check off, with the reason it gives, and counts them:

```text
src/actions/reports.ts:41  oxlint-disable-next-line popcomputer-web/no-sql-interpolation  -- the column names are constants
src/email.ts:12  @ts-expect-error  (no reason given)

2 disable directives, 1 without a reason.
```

It counts Oxlint's and ESLint's `disable` comments, TypeScript's
`@ts-expect-error`, `@ts-ignore` and `@ts-nocheck`, and Effect's
`@effect-diagnostics` comments that lower a rule below `error`, in the files
git tracks or would track. A reason follows ` -- `, as
`// oxlint-disable-next-line popcomputer-web/no-sql-interpolation -- the column names are constants`.

`popweb-fence debt --update` writes the ledger, `lint-debt.json`: each
directive without its line, so moving code changes nothing. Commit it.
`popweb-fence debt --check`, the gate's last step, then fails:

- when the code holds more directives than the ledger, naming the new
  ones. Fix the code each rule reports. A directive the owner accepts goes
  in with `popweb-fence debt --update --allow-increase`, which the command
  hook asks the owner about;
- when the code holds fewer, or different ones, until `--update` records
  them, so the baseline follows the debt down and a later directive cannot
  take the freed place unnoticed.

`--update` never raises the count, and a deleted ledger keeps the count
committed before it. A generated file that turns rules off, such as
Wrangler's `worker-configuration.d.ts`, goes in the ledger's `ignore`, a
list of paths and globs (`src/generated/**`):

```json
{ "count": 0, "ignore": ["worker-configuration.d.ts"], "directives": [] }
```

`--json` prints the directives with their lines, and `--ledger <path>` names
another ledger.

## Boundaries and sign-off

The hook enforces the steps it can see. `AGENTS.md`'s "Boundaries and
sign-off" section lists all of them: what an agent changes alone, and what
needs the owner. Copy it into the application's own `AGENTS.md`, add the
application's own steps, and keep the hook's list and the section's in
step.

---

<!-- docs/auth-plugins.md -->

# Better Auth's plugins

Better Auth's plugins (organizations and teams, two-factor, magic links,
OAuth providers, passkeys, admin) stay Better Auth's: add them to
`betterAuth({ plugins })` and their tables to the schema, and call their
endpoints by name, as `betterAuthRedirect` and `betterAuthCall` call any
other, typed from the registered client. Where they meet the application:

- A plugin's session fields, such as the organization plugin's
  `activeOrganizationId` or the admin plugin's `impersonatedBy`, reach
  `authorize()` once `betterAuthSession` is given the `session` table.
- Two-factor: signing in a member with two-factor on answers
  `{ twoFactorRedirect: true }` rather than a session, so the sign-in's
  `redirectTo` is `(result) => 'twoFactorRedirect' in result ? paths.twoFactor : paths.dashboard`,
  and the code form's action calls `betterAuthRedirect('verifyTOTP', { body: input }, { redirectTo, errors })`.
- An OAuth provider, a company's own or GitHub's: see
  [Signing in with an OAuth provider](#signing-in-with-an-oauth-provider).
- A magic link, or another link Better Auth emails: email a link to a page
  whose button posts its token, as the verify-email link does ([Proving an
  address](auth.md#proving-an-address)), never Better Auth's own `url`. Its
  token signs in once, whoever sends it, so a mail scanner's or a link
  preview's fetch would hold the member's session and leave their click an
  expired link. The post's action, `betterAuthRedirect('magicLinkVerify',
  { query: input }, { redirectTo })`, fails as a rejection does once the link
  is used or expired, so it shows a page instead:
  `.pipe(Effect.catchTag('ValidationError', () => render('Auth/LinkExpired')))`.
  Beside password sign-up, keep `createAuth`'s `requireEmailVerification`: a
  link's first sign-in revokes the password and sessions of an account someone
  else registered with that address, not a two-factor challenge they hold or a
  password sign-in under way, as [Proving an address](auth.md#proving-an-address) says.
- Phone numbers: `requireEmailVerification` gates passwords only. The
  phone-number plugin's verify signs in whoever holds a number's code, whether
  or not anyone has proven the address, and the owner's first sign-in by a
  link leaves the number on the account. So no sign-up sets one:
  `betterAuthHandler` refuses `phoneNumber` unless `settable` names it, as it
  refuses every plugin's user field, and the sign-up action's schema leaves it
  out. A member adds a number once signed in, through `/phone-number/verify`
  with `updatePhoneNumber: true`.
- Organizations: the plugin's `member` table is the membership a guard reads,
  as [Roles belong to memberships](guards.md#roles-belong-to-memberships-read-by-a-guard)
  shows, with the organization bound by its route, its binding saying the
  guard decides: `organization: routeBinding(schema.organization, { guarded: true })`.
  Check a role in the
  guard or the action before calling the plugin's endpoint, so a member
  without it gets a 403: the plugin's own refusal fails as a rejection does,
  sending the form back with its message. The plugin stores any slug, `..`
  and `{organization}` included, and `betterAuthHandler` forwards its create
  and update as they are: refuse a slug `alphaDash` would refuse in
  `organizationHooks.beforeCreateOrganization` and `beforeUpdateOrganization`,
  as your own actions do with `alphaDash`, since `href` leaves a `..` slug's
  link unfilled.
- Writes that must happen together: Better Auth writes each row in its own
  statement, which on D1 is never a transaction. The organization plugin's
  `createOrganization` checks the slug is free, writes the organization, then
  its owner's membership, so a failure between leaves an organization nobody
  owns, and two requests for one slug end in a 500. On D1, write an
  organization and its owner in one `dbBatch` of your own, into the plugin's
  tables, and turn the plugin's off with `allowUserToCreateOrganization:
  false`. Give the tables the constraints its checks stand in for (a unique
  slug, one membership per person and organization, one pending invitation
  per address), so a second, simultaneous request fails rather than writes a
  duplicate.

The package's own tests drive each of these through an application on every
Better Auth release it supports.

## Signing in with an OAuth provider

A provider Better Auth knows, such as GitHub or Google, goes in
`betterAuth({ socialProviders })`; any other OAuth 2.0 or OpenID Connect
provider, such as a company's own, goes in the `genericOAuth` plugin. Either
way, signing in is Better Auth's `signInSocial` with the provider's id, and
the provider sends the browser back to Better Auth's callback,
`/api/auth/callback/{provider}`:

```ts
// src/acme-auth.ts
import { betterAuth } from 'better-auth'
import { drizzleAdapter } from 'better-auth/adapters/drizzle'
import { genericOAuth } from 'better-auth/plugins'
import type { Database } from './db'
import * as schema from './schema'

export interface CreateAcmeAuthOptions {
  readonly db: Database
  readonly secret: string
  readonly baseURL: string
  readonly clientId: string
  readonly clientSecret: string
}

export function createAcmeAuth(options: CreateAcmeAuthOptions) {
  return betterAuth({
    database: drizzleAdapter(options.db, { provider: 'pg', schema }),
    secret: options.secret,
    baseURL: options.baseURL,
    plugins: [
      genericOAuth({
        config: [{
          providerId: 'acme',
          clientId: options.clientId,
          clientSecret: options.clientSecret,
          authorizationUrl: 'https://id.acme.example/oauth/authorize',
          tokenUrl: 'https://id.acme.example/oauth/token',
          userInfoUrl: 'https://id.acme.example/oauth/userinfo',
          pkce: true,
        }],
      }),
    ],
    // A person is their account at the provider, not an email address: an
    // account there reporting someone's email is refused, not given theirs.
    account: { accountLinking: { disableImplicitLinking: true } },
    // A refused sign-in lands on the application's page, with `?error=`.
    onAPIError: { errorURL: '/login' },
    // Better Auth allows three sign-ins from one address in ten seconds, and
    // an office signs in through one address.
    rateLimit: { enabled: true, storage: 'memory', customRules: { '/sign-in/social': { window: 60, max: 30 } } },
  })
}
```

A sign-in button posts to an action that starts the sign-in. The provider is
another site, so the answer to an Inertia visit is the 409 and
`X-Inertia-Location` Inertia asks for, and it loads the provider as a full
page:

```ts
// src/actions/acme.ts
import { action } from '@popcomputer/web/effect'
import { betterAuthRedirect } from '@popcomputer/web/auth'
import { paths } from '../paths'

export const signInWithAcme = action(
  betterAuthRedirect('signInSocial', {
    body: { provider: 'acme', callbackURL: paths.projects, errorCallbackURL: paths.login },
  }, { redirectTo: (result) => result.url ?? paths.login })
)
```

Register it for guests, and Better Auth's handler on the callback alone, so
no other endpoint of Better Auth's is reachable past the application's
guards:

```ts
import { RequireGuestLayer } from '@popcomputer/web/effect'
import { betterAuthHandler } from '@popcomputer/web/auth'
import { signInWithAcme } from '../actions/acme'

routes.provide(RequireGuestLayer).post(paths.loginWithAcme, signInWithAcme)
routes.get(paths.authCallback, betterAuthHandler())
```

Better Auth checks the callback's `state` against a cookie it set in the
browser that started the sign-in, so a sign-in finished in another browser
is refused. `auth.signInLimits` does not count sign-ins through a provider
against the client's address: they check no password here.

A refused sign-in lands on `errorURL` with Better Auth's code as `?error=`,
which the sign-in page turns into words: `state_mismatch` (finished in
another browser, or too late), `account_not_linked` (an account here already
has that email), `unable_to_get_user_info`, and any code the application's
own hooks throw. Decide what an email the provider has not verified may do:
with implicit linking off, an account created from one holds that address
against its real owner. To refuse one, throw from
`databaseHooks.user.create.before`, as
`throw new APIError('FORBIDDEN', { message: 'Your email is not verified.', code: 'email_not_verified' })`
with `APIError` from `better-auth/api`; returning `false` fails the sign-in
without a code. A person's name and email are the provider's at their first
sign-in and stay so unless the provider's config sets `overrideUserInfo:
true`, which fails a later sign-in whose email another account here holds.

A test stands in for the provider with `testOAuthProvider` from
`@popcomputer/web/testing`, which answers the application's `fetch` requests
to the provider's token and user info endpoints as the provider would,
refusing what it would refuse: a code exchanged twice, or without the
client's secret or the PKCE verifier its authorization named. `signIn` starts
the sign-in through the application's route and returns the callback's
answer, as the provider sends the browser back once the person has signed in
there:

```ts
import { afterEach, beforeEach, expect, test } from 'bun:test'
import { testBrowser, testEnv, testOAuthProvider } from '@popcomputer/web/testing'

const acme = testOAuthProvider({
  authorizationUrl: 'https://id.acme.example/oauth/authorize',
  tokenUrl: 'https://id.acme.example/oauth/token',
  userInfoUrl: 'https://id.acme.example/oauth/userinfo',
  client: { id: 'test-client', secret: 'test-secret' },
})

beforeEach(() => acme.install())
afterEach(() => acme.restore())

test('a person signs in with their Acme account', async () => {
  const browser = testBrowser(app, testEnv(testBindings, { database: testDb }))
  const res = await acme.signIn(browser, paths.loginWithAcme, { id: 'acme-1', email: 'ada@example.com', name: 'Ada' })

  expect(res.headers.get('Location')).toBe(paths.projects)
})
```

`authorization(response)` and `callback(authorization, person)` take the
same steps one at a time, for a test of a sign-in finished in another
browser, and `accessTokens` holds the tokens it issued, for a test that no
page shows one. A person's `emailVerified: false` tests what an unverified
email at the provider can reach.

---

<!-- docs/auth-tables.md -->

# Better Auth's tables

Better Auth reads and writes five tables, which the application's schema
declares beside its own: `user`, `session`, `account`, `verification`, and
`rateLimit`, where `auth.signInLimits` counts each account's sign-ins.
`npx @better-auth/cli generate` writes them from the configuration; these
are the tables Better Auth 1.7 needs for it, in a module `src/schema.ts`
re-exports with `export * from './auth-schema'`. Their keys in the schema are
the names Better Auth looks them up by; the SQL names are the application's
to choose. A column the application adds to the user, such as a role, goes
in `user`, and `betterAuthFields` tells Better Auth about it.

<details>
<summary>Better Auth's tables on Postgres</summary>

```ts
// src/auth-schema.ts
import { bigint, boolean, index, integer, pgTable, text, timestamp } from 'drizzle-orm/pg-core'

export const user = pgTable('user', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  emailVerified: boolean('email_verified').notNull().default(false),
  image: text('image'),
  createdAt: timestamp('created_at').notNull().defaultNow(),
  updatedAt: timestamp('updated_at').notNull().defaultNow(),
})

export const session = pgTable(
  'session',
  {
    id: text('id').primaryKey(),
    expiresAt: timestamp('expires_at').notNull(),
    token: text('token').notNull().unique(),
    createdAt: timestamp('created_at').notNull().defaultNow(),
    updatedAt: timestamp('updated_at').notNull(),
    ipAddress: text('ip_address'),
    userAgent: text('user_agent'),
    userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
  },
  (table) => [index('session_user_id_idx').on(table.userId)]
)

export const account = pgTable(
  'account',
  {
    id: text('id').primaryKey(),
    accountId: text('account_id').notNull(),
    providerId: text('provider_id').notNull(),
    userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
    accessToken: text('access_token'),
    refreshToken: text('refresh_token'),
    idToken: text('id_token'),
    accessTokenExpiresAt: timestamp('access_token_expires_at'),
    refreshTokenExpiresAt: timestamp('refresh_token_expires_at'),
    scope: text('scope'),
    password: text('password'),
    createdAt: timestamp('created_at').notNull().defaultNow(),
    updatedAt: timestamp('updated_at').notNull(),
  },
  (table) => [index('account_user_id_idx').on(table.userId)]
)

export const verification = pgTable(
  'verification',
  {
    id: text('id').primaryKey(),
    identifier: text('identifier').notNull(),
    value: text('value').notNull(),
    expiresAt: timestamp('expires_at').notNull(),
    createdAt: timestamp('created_at').notNull().defaultNow(),
    updatedAt: timestamp('updated_at').notNull().defaultNow(),
  },
  (table) => [index('verification_identifier_idx').on(table.identifier)]
)

// Each account's sign-ins, which auth.signInLimits counts.
export const rateLimit = pgTable('rate_limit', {
  id: text('id').primaryKey(),
  key: text('key').notNull().unique(),
  count: integer('count').notNull(),
  lastRequest: bigint('last_request', { mode: 'number' }).notNull(),
})
```

</details>

<details>
<summary>Better Auth's tables on Cloudflare D1</summary>

```ts
// src/auth-schema.ts on Cloudflare D1, in place of the Postgres one
import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'

const createdAt = () => integer('created_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date())
const updatedAt = () => integer('updated_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date())

export const user = sqliteTable('user', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  emailVerified: integer('email_verified', { mode: 'boolean' }).notNull().default(false),
  image: text('image'),
  createdAt: createdAt(),
  updatedAt: updatedAt(),
})

export const session = sqliteTable(
  'session',
  {
    id: text('id').primaryKey(),
    expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
    token: text('token').notNull().unique(),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
    ipAddress: text('ip_address'),
    userAgent: text('user_agent'),
    userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
  },
  (table) => [index('session_user_id_idx').on(table.userId)]
)

export const account = sqliteTable(
  'account',
  {
    id: text('id').primaryKey(),
    accountId: text('account_id').notNull(),
    providerId: text('provider_id').notNull(),
    userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
    accessToken: text('access_token'),
    refreshToken: text('refresh_token'),
    idToken: text('id_token'),
    accessTokenExpiresAt: integer('access_token_expires_at', { mode: 'timestamp_ms' }),
    refreshTokenExpiresAt: integer('refresh_token_expires_at', { mode: 'timestamp_ms' }),
    scope: text('scope'),
    password: text('password'),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
  },
  (table) => [index('account_user_id_idx').on(table.userId)]
)

export const verification = sqliteTable(
  'verification',
  {
    id: text('id').primaryKey(),
    identifier: text('identifier').notNull(),
    value: text('value').notNull(),
    expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
    createdAt: createdAt(),
    updatedAt: updatedAt(),
  },
  (table) => [index('verification_identifier_idx').on(table.identifier)]
)

// Each account's sign-ins, which auth.signInLimits counts.
export const rateLimit = sqliteTable('rate_limit', {
  id: text('id').primaryKey(),
  key: text('key').notNull().unique(),
  count: integer('count').notNull(),
  lastRequest: integer('last_request').notNull(),
})
```

</details>

---

<!-- docs/auth.md -->

# Auth

The Better Auth helpers cover session loading, authenticated and guest routes,
form actions, logout, and public user projection.

`authorize()` requires a signed-in user and returns the parsed `{ user,
session }`. Given a predicate, it also requires the route's own rule:

```ts
const auth = yield* authorize()
const verified = yield* authorize(({ user }) => user.emailVerified)
```

Without a signed-in user, both fail with `UnauthorizedError`; when the
predicate returns `false`, the second fails with `ForbiddenError`.

`auth.session` decodes Better Auth's session response into the signed-in
user, so a dependency response is never trusted because it looks
session-shaped. `betterAuthSession(tableSchema(schema.user))` takes the user
from the `user` table, so a field the application adds, such as a `role`, is
declared in the table, and `authorize()`, `currentUser` and `signedIn`
follow. A plugin
that adds session fields, such as the organization plugin's
`activeOrganizationId`, adds their columns to the `session` table: give
`betterAuthSession` that table too,
`betterAuthSession(tableSchema(schema.user), tableSchema(schema.session))`,
and `authorize()` returns them. Better Auth learns of the field from the same table:
`user: { additionalFields: betterAuthFields(schema.user, { role: { input: false } }) }`
in `createAuth` takes each field's type, enum values and whether it is
required from its column, and `input` says whether a visitor may set it at
sign-up. Give a narrowed column an enum, so the session checks its values, and
take it from the Effect schema the application validates input with, so the
role is declared once: `text('role', { enum: Role.literals })` for
`const Role = S.Literals(['admin', 'member'])`. The session token is `Redacted`, so
serializing the auth user never exposes it; read it with `Redacted.value`
where it is needed. `auth.share` names the fields pages receive as
`auth.user`.

Machine clients, such as a door scanner calling a JSON API, authenticate with
Better Auth's `bearer()` plugin: a request with `Authorization: Bearer
<token>` loads its user as a session cookie does, with no setup of the
framework's own.

## Better Auth's client

`setupWeb`'s `auth.client` builds Better Auth, on [its tables](auth-tables.md),
from a small factory beside `src/db.ts`, which the [Quick start](setup.md#3-configure-the-application-once-and-register-it) shows:

```ts
// src/auth.ts
import { betterAuth, type BetterAuthOptions } from 'better-auth'
import { drizzleAdapter } from 'better-auth/adapters/drizzle'
import type { Database } from './db'
import { paths } from './paths'
import * as schema from './schema'

export interface CreateAuthOptions {
  readonly db: Database
  readonly secret: string
  /** The origin emailed links name: a declared var, never the request's URL. */
  readonly baseURL: string
  /** Delivers an email through the application's mail provider. */
  readonly sendEmail: (email: { readonly to: string; readonly subject: string; readonly text: string }) => Promise<void>
  readonly advanced?: BetterAuthOptions['advanced']
}

// Better Auth's tables (user, session, account, verification, rateLimit)
// belong in ./schema, as auth-tables.md shows.
export function createAuth(options: CreateAuthOptions) {
  return betterAuth({
    database: drizzleAdapter(options.db, { provider: 'pg', schema }),
    secret: options.secret,
    baseURL: options.baseURL,
    // A password signs in only once its address is proven, so an account
    // registered with someone else's address holds no session, password or
    // two-factor challenge when its owner signs in by a link or a provider.
    emailAndPassword: { enabled: true, requireEmailVerification: true },
    // The link proves the address and signs nobody in: the member signs in next.
    emailVerification: {
      sendVerificationEmail: ({ user, token }) => options.sendEmail({
        to: user.email,
        subject: 'Confirm your email address',
        text: `Confirm your email address to finish signing up:\n${options.baseURL}${paths.verifyEmail}?${new URLSearchParams({ token })}\n\n` +
          'If you did not sign up, ignore this email and do not follow the link: ' +
          'whoever signed up with your address chose its password, and confirming it would let them sign in as you.',
      }),
    },
    // setupWeb's auth.signInLimits limits signing in, up and every password
    // call by address and account. Better Auth's own limits stay on too, in
    // each isolate's memory (its 'database' storage deletes the accounts'
    // counts, so auth.signInLimits refuses it): three sign-ins or sign-ups
    // from one address in ten seconds, and its other endpoints. They are on
    // by default only when NODE_ENV is 'production', which a Worker's is not.
    rateLimit: { enabled: true, storage: 'memory' },
    advanced: {
      ...options.advanced,
      // Cloudflare's header, which a client cannot write; X-Forwarded-For it can.
      ipAddress: { ipAddressHeaders: ['cf-connecting-ip'], ...options.advanced?.ipAddress },
    },
  })
}

export interface CreateStatelessAuthOptions {
  readonly secret: string
  readonly advanced?: BetterAuthOptions['advanced']
}

// Better Auth without a database, for an application without accounts of its own.
export function createStatelessAuth(options: CreateStatelessAuthOptions) {
  return betterAuth({ secret: options.secret, advanced: options.advanced })
}
```

The `backgroundTasks` object has Better Auth's
`advanced.backgroundTasks` shape. Passing it through makes session refreshes,
email callbacks, and plugin work part of the request lifecycle: Workers use
`waitUntil`, while local and test runtimes finish the work before teardown.

Actions call Better Auth with `betterAuthRedirect` and `betterAuthCall`, as
[Signing in and out](sign-in.md) shows: they name the endpoint and
send the call through Better Auth's request handler, so its rate limits,
origin checks and plugins' hooks apply. An action reads the signed-in user
with `authorize()` or `currentUser`, never with a `getSession` call. Code
outside an action, such as a Durable Object reading the session from the
headers a request handed it, calls Better Auth's own `auth.api`, as Better
Auth documents. A refusal it throws is Better Auth's `APIError`, which code
can recognise without importing it: its `name` is `'APIError'`, its
`statusCode` the HTTP status and its `body.code` the reason, such as
`INVALID_EMAIL_OR_PASSWORD`.

## Proving an address

`createAuth` signs no one in by a password whose address nobody has proven.
Signing up sets no session: Better Auth emails the link `sendEmail` delivers,
to `paths.verifyEmail`, and the sign-up action redirects to a page asking the
visitor to check their inbox; a password sign-in before then is refused as
`Email not verified`. A sign-up for a registered address is answered as a new
one is, and sends nothing, so the form tells no one who has an account. The
mailer is the application's own: `src/email.ts` exports `sendEmail(env, { to,
subject, text })`, which calls its mail provider's API. The link opens a page
whose button posts its token back, so a mail scanner that fetches the link
proves nothing. The post proves the address and signs nobody in; the member
signs in with a password next:

```ts
// src/actions/verify-email.ts
import { Effect, Schema as S } from 'effect'
import { action, redirect, render, validateRequest } from '@popcomputer/web/effect'
import { betterAuthRedirect } from '@popcomputer/web/auth'
import { href } from '@popcomputer/web/paths'
import { requiredString } from '@popcomputer/web/schema'
import { paths } from '../paths'

const Link = S.Struct({ token: requiredString })
const expired = () => redirect(href(paths.login, {}, { error: 'link_expired' }))

export const showVerifyEmail = action(
  Effect.gen(function* () {
    const input = yield* validateRequest(Link)

    return yield* render('Auth/VerifyEmail', input)
  }).pipe(Effect.catchTag('ValidationError', expired))
)

export const verifyEmail = action(
  Effect.gen(function* () {
    const input = yield* validateRequest(Link)

    return yield* betterAuthRedirect('verifyEmail', { query: input }, { redirectTo: paths.login })
  }).pipe(Effect.catchTag('ValidationError', expired))
)
```

Register both for everyone, `routes.get(paths.verifyEmail, showVerifyEmail)`
and `.post(paths.verifyEmail, verifyEmail)`, beside the page
`'Auth/VerifyEmail': S.Struct({ token: S.String })`; a link that expired,
after an hour, lands on the sign-in page with `?error=`. Email this page's
link, not Better Auth's own `url`, which proves the address on any fetch. A
link Better Auth's `user.changeEmail` sends to a new address completes only
signed in to the account that asked to move there: Better Auth would sign
anyone else who follows it in to that account, so the framework sends them
to sign in.

Without `requireEmailVerification`, someone who registers another person's
address first is signed in, and keeps what the owner's magic-link or provider
sign-in does not revoke: a two-factor challenge or a password sign-in under
way. Leave `autoSignInAfterVerification` off, or an owner who follows a link
for an account someone else registered is signed in to it.

One risk remains, and the email warns of it: an owner who follows the link
for an account they never created proves the address for whoever chose its
password, which then signs in, and a later magic-link sign-in revokes
nothing. A password reset takes the account back: an application that adds
one sets `emailAndPassword.revokeSessionsOnPasswordReset: true`, so a reset
also ends the sessions the old password began.

## Limiting password guessing

Better Auth's own limits count each client address, so guesses at one
account's password spread across a botnet's addresses are never slowed, and
each one costs a password hash. `setupWeb`'s `auth.signInLimits` limits both,
cheapest first:

- A Cloudflare Workers Rate Limiting binding counts each client address's sign-in, sign-up
  and password calls, an IPv6 address's by its network, whose owner can send from any
  address in it: its first `ipv6Prefix` bits, 64 by default. It counts each account's
  sign-ins too, at Cloudflare's edge, writing nothing. `limiter` names it, one `src/env.ts`
  types `RateLimit`. Declare it in `wrangler.jsonc`; its `period` is 10 or 60 seconds:

  ```jsonc
  "ratelimits": [{ "name": "SIGN_IN_LIMITER", "namespace_id": "1001", "simple": { "limit": 5, "period": 60 } }]
  ```

- `table`, Better Auth's `rateLimit` table, counts each account's sign-ins
  before their passwords are checked, so guesses sent together count against
  each other. Past `failures.max`, 10, a sign-in is refused unhashed for
  `failures.cooldown`, a minute, doubled by each further one up to
  `failures.window`, 15 minutes, which the count lasts past its cooldown's
  end. A cooldown, not a lock: someone who knows an address can slow its
  owner down, never shut them out. A success deletes the row, whose key is a
  hash of the account, not its address.

An account is what its sign-in's endpoint finds it by, whatever else the body
sends: the email `/sign-in/email` reads, the phone-number plugin's
`/sign-in/phone-number`, or the username plugin's `/sign-in/username` as its
`usernameNormalization` folds it, so the spellings it folds share one count.
A password sign-in whose field is missing, blank or not text is refused with
a 400 before its password is checked. Each door counts apart: an account that
signs in by email and by username has a budget for each.

`betterAuthRedirect`, `betterAuthCall` and `betterAuthHandler` all apply the
limits. A refused call fails with `AuthRateLimitError`, whose
`retryAfterSeconds` the 429 sends as `Retry-After`. Rows for accounts nobody
tries again stay until a sweep deletes them; run `sweepSignInFailures` from
`@popcomputer/web/auth` from a Cron Trigger:

```ts
import { sweepSignInFailures } from '@popcomputer/web/auth'

export default {
  fetch: app.fetch,
  scheduled: routes.scheduled(() => sweepSignInFailures),
}
```

In tests, give the binding `testRateLimiter({ limit, period })` from
`@popcomputer/web/testing` among the bindings, and read the keys it refused
from its `refused`. It counts by the wall clock, as Cloudflare's does, not by
`testClock`, so a test of cooldowns gives it a limit the test never reaches.
A request whose bindings lack the limiter fails with a message naming it.

---

<!-- docs/background.md -->

# Background, scheduled and queued work

## Work after the response

For runtime-owned work that must outlive a response, name the work and pass
the Effect. The name identifies the work in error reports:

```ts
yield* background('audit.send', sendAuditEvent(event))
```

In a Worker, background work starts at once and runs beside the rest of the
action: the response does not wait for it, and the Worker's execution context
keeps it alive after the response. Without an execution context, as in tests,
it runs where it is called, before the response returns, so a test sees its
effects but not a race between them; pass an execution context as
`app.request`'s fourth argument to test concurrent behaviour. Tags the work
names with `purgeCache` are purged once it succeeds, and a failed purge is
reported as the work's failure. Work handed to `ExecutionContextService`'s
`runInBackground` or `schedule` purges the same way; `purgeCache` called by
work that outlived what it belongs to, such as a detached fiber, is a defect
rather than a purge nothing would send.

## Scheduled and queued work

A Cron Trigger's and a Queue consumer's work runs with the application's
services, as an action does: the database, the layers given to
`web.services`, `Config` and
`background()`, and the layers a builder was given with `provide`.
`routes.scheduled(job)` and `routes.queue(Schema, handle)` return the Worker's
`scheduled` and `queue` handlers, and type-check the job as a registration
does, so one that needs a service the routes do not provide is a
`missingServices` error.

```ts
import { lt } from 'drizzle-orm'
import { DateTime } from 'effect'
import { orders } from '../schema'

const forgetAbandonedOrders = Effect.gen(function* () {
  const cutoff = DateTime.toDateUtc(DateTime.subtract(yield* DateTime.now, { days: 30 }))

  yield* dbMutation((db) => db.delete(orders).where(lt(orders.paidAt, cutoff)))
})

// What the queue carries is declared once, as a schema.
const Reminder = S.Struct({ orderId: S.String })

export default {
  fetch: app.fetch,
  scheduled: routes.scheduled((event) => event.cron === '0 3 * * *' ? forgetAbandonedOrders : Effect.void),
  queue: routes.queue(Reminder, (reminder) => Effect.log('reminder', reminder.orderId)),
}
```

A scheduled job that fails rejects, so the platform records a failed run. The
queue handler decodes each message's body with the schema and handles the
messages one at a time: one whose work succeeds is acknowledged, and one whose
body does not decode, or whose work fails, is logged and left for the queue
to retry, after which the queue drops it or moves it to its dead-letter
queue. The handler also receives the message's `id` and `attempts`, for work
that must happen once however often a message is delivered. A job whose
`purgeCache` purge fails has failed too: it rejects, and the queue retries
the message.

A test calls the handlers as the platform does, with `testEnv`'s bindings, so
its fakes, clock and database apply. `testBatch` from
`@popcomputer/web/testing` makes a batch that records which messages were
acknowledged and which were left to retry:

```ts
import { testBatch, testEnv } from '@popcomputer/web/testing'

const worker = {
  scheduled: routes.scheduled(() => Effect.log('nightly sweep')),
  queue: routes.queue(S.Struct({ orderId: S.String }), (reminder) => Effect.log(reminder.orderId)),
}

const time = await testClock()
await worker.scheduled({ cron: '0 3 * * *', scheduledTime: Date.now() }, testEnv(time.layer, testBindings))

const batch = testBatch([{ orderId: 'order-1' }, { orderId: 42 }])
await worker.queue(batch, testEnv(testBindings))
batch.acked() // [{ orderId: 'order-1' }]
batch.retried() // [{ orderId: 42 }], which does not decode
```

`routes.run(effect, env, ctx)` runs any other Effect the same way, such as a
one-off job from a script, resolving with its value.

## Other patterns

- **Work after the response**, such as a confirmation email:
  `background('order-email', mailer.send(...))`. Its failure is reported, not
  shown to the visitor, so it must not be the only record of something the
  visitor needs.

---

<!-- docs/constraints.md -->

# Constraints keep invariants that concurrent requests would break

A rule the database can state is safest stated there: a `CHECK (stock >= 0)`
on the stock column, a unique index on an order's idempotency key, a unique
event id for a webhook. A write that would break one fails with
`DatabaseConstraintViolation`, whose `constraint` says which kind
(`'unique'`, `'check'`, `'foreign-key'`, `'not-null'`, `'exclusion'`,
`'trigger'`) and `constraintName` which one, and the whole `dbTransaction`,
or the whole `dbBatch` on Cloudflare D1, is undone. A rule no `CHECK` or
unique index can state, such as no two interviews of one interviewer
overlapping, is an exclusion constraint on Postgres (`EXCLUDE USING gist`,
which on a text or uuid column needs `CREATE EXTENSION IF NOT EXISTS
btree_gist` in a custom drizzle-kit migration, and PGlite in tests
`new PGlite({ extensions: { btree_gist } })` from
`@electric-sql/pglite/contrib/btree_gist`) and a trigger on SQLite and D1
(`SELECT RAISE(ABORT, 'interviewer_double_booked')`, in a migration from
`drizzle-kit generate --custom`; a time window it counts compares the rows'
own timestamps with the new row's, `NEW.created_at`, rather than
`unixepoch()`, so the test clock moves it), whose raised text is
the `constraintName`. `constraintFieldErrors({ leases_no_overlap: {
startDate: 'Another lease covers these dates.' } })` shows a named rule of any
kind beside the fields it covers. The same action works on both, with no
count-then-write race:

```ts
import { eq, sql } from 'drizzle-orm'
import { positiveInt, requiredString } from '@popcomputer/web/schema'
import { orders, products } from '../schema'

const Order = S.Struct({ productId: requiredString, quantity: positiveInt })

export const placeOrder = action(Effect.gen(function* () {
  const auth = yield* authorize()
  const request = yield* RequestService
  const input = yield* validateRequest(Order)
  // The client sends one key per checkout, so a double submit repeats it.
  const idempotencyKey = request.header('Idempotency-Key') ?? crypto.randomUUID()

  return yield* dbTransaction(Effect.gen(function* () {
    yield* dbMutation((db) => db.insert(orders).values({
      id: crypto.randomUUID(),
      userId: auth.user.id,
      idempotencyKey,
      ...input,
    }))
    yield* dbMutation((db) =>
      db.update(products)
        .set({ stock: sql`${products.stock} - ${input.quantity}` })
        .where(eq(products.id, input.productId))
    )
  })).pipe(
    Effect.andThen(flash('success', 'Order placed.')),
    Effect.andThen(redirect(paths.dashboard)),
    Effect.catchTag('DatabaseConstraintViolation', (violation) => Effect.gen(function* () {
      if (violation.constraint === 'check') {
        return yield* invalid({ quantity: 'There are not that many left.' })
      }

      // The first submit already placed this order.
      if (violation.constraint === 'unique') return yield* redirect(paths.dashboard)

      return yield* violation
    }))
  )
}))
```

A handler whose branches end differently, as this one does, branches inside
`Effect.gen`: TypeScript combines the branches of one generator, but not a
plain function that returns a different Effect from each branch.

`columns` names the columns as the database reports them: snake_case SQL
names on D1 (`['idempotency_key']`), which `uniqueFieldErrors` matches against
the schema's camelCase keys too. An index on an expression, such as
`lower(email)`, reports no columns, only its name: `uniqueFieldErrors({ email:
'A contact has this email.' }, { constraints: { contacts_email_lower_unique:
'email' } })` puts it on its field. SQLite and D1 report a constraint by its
columns instead, so name a composite key that belongs on another field by
them, in any order and in either case: `{ constraints: { 'org_id,user_id':
'email' } }`. A composite key reports each of its columns, so a message keyed
by one of them, `{ sku: 'Taken.' }` for a key on `(company_id, sku)`, already
matches; `constraints` is for a field that is not one of them. In
development, the error page of a violation no mapping matched shows the
`constraints` entry that would map it. The kind, columns and name come from
the database's own report, never from the statement's values, which Drizzle's
error repeats: a submitted value that reads like a constraint message changes
none of them. On SQLite, only a constraint's report counts, a
`SQLITE_CONSTRAINT` code or D1's message ending in that result: its other
errors, such as a JSON path or a search it rejects, quote the value and stay
a `DatabaseError`.

An update of a row that is not there changes nothing and fails nothing: read
`meta.changes` on D1, or `.returning()`, to tell. SQLite checks a `CHECK`
before an upsert's conflict, so `INSERT ... ON CONFLICT DO UPDATE` whose
inserted values break the check fails even when the row exists; insert a
starting row with `onConflictDoNothing()` and update it after, in the same
batch.

On D1, write the same statements as one `dbBatch((db) => [...])`. They run
in order and the first that breaks a constraint undoes the batch, so it is
the one whose violation the action sees: put the statement a retry depends
on, such as an optimistic lock's unique sequence, first. A violation the
action does not map answers 409. A batch can also be a list
built at run time, such as one statement per line of a form,
`dbBatch((db) => lines.map((line) => db.update(...)))`, whose results are a
list; a helper that returns statements for a batch takes the `db` the batch
passes it, typed `DatabaseType` from `@popcomputer/web/effect`, and types them
`BatchStatement`. A batch
cannot branch on an earlier statement's result, so a write that depends on
one carries its condition in its own `WHERE`: an insert selects its row,
`rowOf(table, values)` from `@popcomputer/web/drizzle`, from a query that
returns no row when the condition fails, and an update adds
`WHERE EXISTS (...)`. `rowOf` gives every column of the table in its order,
the values given bound as their columns encode them, and the columns left out
their defaults, so a misnamed column is a type error; a value may be SQL or
a column of the table the insert selects from. An inserting
statement's `.returning()`, or an update's `meta.changes`, tells the action
whether it applied:

```ts
import { and, eq, lt, sql } from 'drizzle-orm'
import { rowOf } from '@popcomputer/web/drizzle'
import { tasks } from '../schema'

// Adds the task only while its project holds fewer than 100; returns no row otherwise.
const addTaskIfRoom = (projectId: string, title: string) =>
  dbMutation((db) =>
    db.insert(tasks).select(
      db.select(rowOf(tasks, { id: crypto.randomUUID(), projectId, title }))
        .from(projects)
        .where(and(
          eq(projects.id, projectId),
          lt(sql`(select count(*) from ${tasks} where ${tasks.projectId} = ${projects.id})`, 100)
        ))
    ).returning({ id: tasks.id })
  )
```

When a limit cannot be a constraint, a guarded update such as
`UPDATE ... WHERE (SELECT count(*) ...) < 100` that changed no row
(`meta.changes === 0`) is the limit refusing it. A statement can depend on
the one before it through SQLite's `changes()`, the rows the previous
statement changed: ``sql`changes() = 1` `` in an insert-select's `WHERE`
writes a log row only after an update that applied, in the same batch.

A value the database computes, such as the next ticket number in an
organization, belongs in the insert:
``sql`(SELECT coalesce(max(number), 0) + 1 FROM tickets WHERE organization_id = ${organizationId})` ``.
Pass the outer row's value as a parameter, as here: in a select list Drizzle
writes a column without its table, so ``${organizations.id}`` inside that
subquery names the subquery's own table and silently computes the wrong
value. Name it in full, ``${organizations}.${sql.identifier('id')}``, when it
must be a column; in a `WHERE` Drizzle qualifies columns itself. Write every
statement with the query builder: Drizzle's D1 batch fails at runtime on
`db.run(sql)` with parameters, which is a type error there. D1
binds at most 100 parameters to a statement, so an `IN (...)` over many ids,
or an insert of many rows, goes in chunks.

---

<!-- docs/data-cache.md -->

# The data cache

The data cache keeps computed values in a store, checked against an Effect
Schema when read. Provide a store with `kvCache` as a `request` layer of
`web.services`; KV
keeps an entry at least 60 seconds, its shortest expiry, and `cache` still
treats it as fresh only for its `ttl`, counted from when the value is stored,
not from when its computation read its data. `kvCache` keeps its keys under
`popweb:cache:`, so its KV namespace can hold the application's other data,
such as an audit log, which the cache never reads, lists or deletes, even
for `cacheInvalidatePrefix('')`:

```ts
import { kvCache } from '@popcomputer/web/cache'

export const { app, routes } = web.services({
  request: (c) => kvCache(c.env.KV),
})
```

Then wrap a computation in `cache`:

```ts
import { eq } from 'drizzle-orm'
import { Duration, Effect, Schema as S } from 'effect'
import { action, authorize, dbQuery, render } from '@popcomputer/web/effect'
import { cache } from '@popcomputer/web/cache'
import { columnsOf } from '@popcomputer/web/schema'
import { projects } from '../schema'

export const listProjects = action(Effect.gen(function* () {
  const auth = yield* authorize()

  const summaries = yield* cache(
    `users:${auth.user.id}:projects`,
    dbQuery((db) =>
      db.select(columnsOf(projects, ProjectSummary)).from(projects).where(eq(projects.userId, auth.user.id))
    ),
    S.Array(ProjectSummary),
    { ttl: Duration.minutes(5), swr: Duration.minutes(1), version: true }
  )

  return yield* render('Projects/Index', { projects: summaries, next: null })
}))
```

The computation is any Effect, here a `dbQuery`; it runs only when the entry
is missing or stale, and its result is stored through the schema's JSON form, so a `Date` comes back as
a `Date`.

## Tagging cached data

A value that depends on records takes their cache tags, the names a route's
`purges` and `purgeCache` use (see [Time-based caching with Workers
Cache](page-cache.md#time-based-caching-with-workers-cache)). A route that purges one of
them after a write invalidates the value as well as the cached responses, so
what changed is stated once, by the write:

```ts
const summary = yield* cache(
  `projects:${project.id}:summary`,
  summarizeProject(project.id),
  ProjectSummary,
  { ttl: Duration.minutes(5), tags: [recordCacheTag('projects', project.id)] }
)
```

A tag gets a generation in the store when an entry first uses it, and each
purge of the tag replaces it, so an entry stored under an older one is a miss,
for `cacheGet` too. `cache` reads the generations before it computes, so a
purge during the computation leaves its value a miss. So does `cacheSet`
given the Effect that reads its value, since it reads them before running
that Effect:

```ts
yield* cacheSet(`projects:${project.id}:summary`, summarizeProject(project.id), ProjectSummary, {
  ttl: Duration.minutes(5),
  tags: [recordCacheTag('projects', project.id)],
})
```

Given a value read earlier, `cacheSet` records them as they are when it
runs, and cannot know when the value was read: a value read before a write
whose purge ran before `cacheSet` stays until its `ttl`. Give a tagged
`cacheSet` its read, or compute the value through `cache`.
A tagged read costs one store read per tag besides the entry's own; a purge of
a tag no entry uses costs a read and no write. KV accepts one write a second
to a key and takes up to a minute to show a write everywhere, so tag data by
the records it reads rather than by a table written many times a second.

## When the store fails

`cache` never fails because of the store: an unreachable store or an entry that
no longer matches the schema computes the value instead, and the failure goes
to `EffectErrorObserverService`. `cacheGet` and `cacheSet` fail with
`CacheError`, which renders as 503. `cacheInvalidate` and
`cacheInvalidatePrefix`, which follow a write that has already happened,
report a store failure instead of failing the request; the entry stays until
it expires.
Stale-while-revalidate refreshes in the background when the request has an
execution context and inline otherwise.

## Caching an API that authenticates each request

The route `cache` option never stores a response to a request with an
`Authorization` header: it answers `no-store`. Workers Cache answers a hit
before the Worker runs, so a stored response would reach a revoked key and
skip the key's rate limit. Authenticate every request and cache the data the
response is built from instead, keyed by what it depends on, such as the
project an API key belongs to, so every key of that project shares one entry.
Tag it with the records it reads, and the writes that purge them invalidate
it: `purges: true` on `PUT /projects/{project}/tasks/{task}` purges the
project's tag.

```ts
export const projectTasks = action(Effect.gen(function* () {
  // The key's project, or new UnauthorizedError({ message: 'This API key is not valid.', challenge: 'Bearer' }),
  // which a JSON client receives as a 401 with WWW-Authenticate: Bearer.
  const project = yield* apiKeyProject

  const tasks = yield* cache(
    `projects:${project.id}:tasks`,
    loadTasks(project.id),
    S.Array(Task),
    { ttl: Duration.seconds(30), tags: [recordCacheTag('projects', project.id)] }
  )

  return yield* json(S.Struct({ tasks: S.Array(Task) }), { tasks })
}))
```

---

<!-- docs/database.md -->

# The database

The database operations read the request's client from `DatabaseService` and
give their callback the application's Drizzle client with its own types:

| Operation | Use |
| --- | --- |
| `dbQuery((db) => ...)` | Reads. |
| `dbMutation((db) => ...)` | One write, or writes that need not be atomic. |
| `dbTransaction(effect)` | An Effect whose database operations must succeed together, on a driver with asynchronous transactions (Postgres, MySQL, libsql). |
| `dbBatch((db) => [...])` | Writes that must succeed together on Cloudflare D1, libsql or Neon HTTP: every statement applies, or none. |

Inside `dbTransaction`, `DatabaseService` is the transaction, so every
`dbQuery` and `dbMutation` the Effect runs takes part, including those of the
services it calls. Domain logic between the writes stays ordinary Effect code:
the transaction commits when the Effect succeeds, and rolls back when it fails
with the Effect's own typed error.

```ts
// src/actions/projects/destroy.ts
import { eq } from 'drizzle-orm'
import { Effect } from 'effect'
import { action, bound, dbMutation, dbTransaction, flash, redirect } from '@popcomputer/web/effect'
import { paths } from '../../paths'
import { projects, tasks } from '../../schema'

export const destroyProject = action(
  Effect.gen(function* () {
    // Its owner's only: the binding is ownedBy 'userId'.
    const project = yield* bound('project')

    yield* dbTransaction(Effect.gen(function* () {
      yield* dbMutation((db) => db.delete(tasks).where(eq(tasks.projectId, project.id)))
      yield* dbMutation((db) => db.delete(projects).where(eq(projects.id, project.id)))
    }))
    yield* flash('success', 'Project deleted.')

    return yield* redirect(paths.projects)
  })
)
```

`dbTransaction` is a type error on Cloudflare D1, which rejects interactive
transactions, and on synchronous drivers such as `bun:sqlite`, which commit
before an awaited write runs. On D1, use `dbBatch`. A batch cannot decide
from a read, so a rule such as "at most 100 open tasks" belongs in the write
itself (`INSERT ... SELECT ... WHERE (SELECT count(*) ...) < 100`, then check
the number of rows changed); a count followed by an insert lets concurrent
requests pass the limit together.

A write that breaks a constraint fails with `DatabaseConstraintViolation`,
which names the constraint kind (`unique`, `foreign-key`, `not-null`, `check`)
and, when the driver reports them, its `columns`. Any other failure is a
`DatabaseError`. `uniqueFieldErrors` turns a unique violation into field errors
the form shows:

```ts
yield* dbMutation((db) => db.insert(projects).values(newProject)).pipe(
  uniqueFieldErrors({ slug: 'A project with this slug already exists.' })
)
```

## Migrations

The package does not run migrations. drizzle-kit generates them from
`src/schema.ts`, and the demo's README shows the commands that generate and
apply them, in [Changing the database](https://github.com/PatrickOgilvie/popcomputer-web-demo#changing-the-database).
[A database for tests](test-database.md) applies the same migrations to a
test's database.

## Lists page through with a cursor

A list that grows pages through it by the last row shown, not by an offset: a
row added or removed between two requests shifts every offset, and the
database counts and skips every row before one. Order by a column that orders
the rows and a unique one that breaks ties, read one row more than the page
holds to learn whether another page follows, and render the cursor of the
last row shown as the page's `next`. The query decodes through
`validateRequest`, so a malformed cursor is a 422 rather than a database
error, and an empty search box is `null`:

```ts
// src/actions/projects/list.ts
import { and, desc, eq, ilike, lt, or } from 'drizzle-orm'
import { Effect } from 'effect'
import { action, authorize, dbQuery, render, validateRequest } from '@popcomputer/web/effect'
import { ProjectFilters } from '../../forms'
import { projects } from '../../schema'

const PAGE_SIZE = 25

export const listProjects = action(Effect.gen(function* () {
  const auth = yield* authorize()
  const filters = yield* validateRequest(ProjectFilters)
  const after = filters.beforeAt !== null && filters.beforeId !== null
    ? { at: filters.beforeAt, id: filters.beforeId }
    : null

  const rows = yield* dbQuery((db) =>
    db.select({ id: projects.id, name: projects.name, createdAt: projects.createdAt })
      .from(projects)
      .where(and(
        eq(projects.userId, auth.user.id),
        filters.q === null ? undefined : ilike(projects.name, `%${filters.q}%`),
        after === null ? undefined : or(
          lt(projects.createdAt, after.at),
          and(eq(projects.createdAt, after.at), lt(projects.id, after.id))
        )
      ))
      .orderBy(desc(projects.createdAt), desc(projects.id))
      .limit(PAGE_SIZE + 1)
  )

  const shown = rows.slice(0, PAGE_SIZE)
  const last = shown.at(-1)

  return yield* render('Projects/Index', {
    projects: shown,
    next: rows.length > PAGE_SIZE && last !== undefined ? { beforeAt: last.createdAt, beforeId: last.id } : null,
  })
}))
```

The page links to the next one with `href(paths.projects, {}, next)`, as
[Forms](forms.md) shows; a search carries on through the
pages when the link adds it, `{ ...next, q }`. The page's schema drops
`createdAt` from each row it shows, since `ProjectSummary` does not name it.
An index on the order's columns, `(user_id, created_at, id)`, lets each page
start where the last one ended.

On Postgres, declare a cursor's timestamp as
`timestamp('created_at', { precision: 3, withTimezone: true })`. The cursor
travels as a JavaScript `Date`, which holds milliseconds, while a plain
`timestamp` holds microseconds, so a row created within the same millisecond
as the last one shown, but before it, falls between the pages and is never
listed. A `timestamp` without a time zone also reads in the process's zone:
Workers run in UTC, but a test on a machine in another zone shifts every
cursor by its offset.

---

<!-- docs/deploying.md -->

# Deploying

The demo's README shows the commands that deploy an application with
Wrangler, in
[Deploying](https://github.com/PatrickOgilvie/popcomputer-web-demo#deploying).
What the framework does around a deploy:

- The Worker's entry imports every module of registrations, as
  [Wire the Worker](setup.md#6-wire-the-worker) shows.
- Each deploy starts the page cache empty once `wrangler.jsonc` binds the
  version metadata, as [Page caching](page-cache.md) shows.
- The sign-in limiter is a Rate Limiting binding declared in
  `wrangler.jsonc`, as [Limiting password guessing](auth.md#limiting-password-guessing)
  shows.
- Each isolate checks the Worker's vars and secrets against `src/env.ts`
  before it serves, and a script checks them before a deploy with
  `checkEnv`, as [Vars and secrets](env.md) shows.

## Version values

Three different versions may appear around an application:

| Value | Meaning | Change it when | Effect of changing it |
|---|---|---|---|
| npm package version | Version of `@popcomputer/web` | You upgrade the dependency | Selects framework code and public API |
| `setupWeb({ version })` | Inertia asset version | Client assets or their manifest change | The next mismatched GET receives an Inertia location response and reloads the current assets |
| cache `version` | Namespace for one cached value shape | The cached schema or interpretation changes | Reads and writes use a fresh cache key |

`createVersion(manifest)` derives the Inertia asset version from manifest asset
paths. It is unrelated to the npm package version. An application without a
client build yet, or a test, passes a constant (`version: '1'`) and changes it
when the client does; export it so tests send the same `X-Inertia-Version`.

The asset version reloads a visitor already on the site when a deploy changes
the client. A page loaded during a deploy needs more: for a few seconds after
`wrangler deploy`, the previous version can still answer at some edge
locations, with a page naming the previous build's scripts, which the new
deploy no longer serves, and the page would stay blank. `createTemplate`
inlines a small script first in every page's head that reloads the page when
one of the template's own scripts or stylesheets fails to load, or a chunk
Vite loads does (`vite:preloadError`). It reloads at once, then after 2 and 4
seconds, and no more than three times a minute in a tab, so a file missing for
another reason never reloads the page in a loop; a script the application adds
through `head`, such as an analytics tag a blocker refuses, never reloads it.
An application that sends its own `Content-Security-Policy` with a
`script-src` allows the script with `TEMPLATE_SCRIPT_HASH` from
`@popcomputer/web`:

```ts
import { TEMPLATE_SCRIPT_HASH } from '@popcomputer/web'

const scriptSrc = `script-src 'self' ${TEMPLATE_SCRIPT_HASH}`
```

---

<!-- docs/endpoints.md -->

# JSON endpoints

A JSON API declares each endpoint once, as a contract: its method, its path
from `src/paths.ts`, the query, body and headers it reads, the body of a
success with its status, and the failures it declares, each with the status
it answers. Everything else derives from the contract, so nothing about an
endpoint is written twice: the action receives its input decoded and returns
the success value, the route takes its method and path from it, a client or a
test calls it with typed input and reads a typed result, and `openApi`
describes every endpoint for a published reference. The module imports only
`effect`, the validators and the paths, so a React bundle or a separate
client imports it without the server.

An application that is only an API leaves `version` and `render` out of
`setupWeb`: without a template it answers only JSON, every failure an unknown
path's included, whatever the client asks for, and rendering a page is a
configuration error.

```ts
// src/endpoints.ts
import { Schema as S } from 'effect'
import { endpoint } from '@popcomputer/web/endpoint'
import { alphaDash, coercedNumber, nullableString, requiredString } from '@popcomputer/web/schema'
import { paths } from './paths'

export const ApiProject = S.Struct({
  id: S.String,
  name: S.String,
  slug: S.String,
  createdAt: S.Date,
})

export class SlugTaken extends S.TaggedError<SlugTaken>()('SlugTaken', {
  slug: S.String,
  message: S.String,
}) {}

export const endpoints = {
  listProjects: endpoint.get(paths.apiProjects, {
    summary: 'List your projects, newest first.',
    auth: true,
    query: S.Struct({ limit: coercedNumber, q: nullableString }),
    success: S.Struct({ data: S.Array(ApiProject) }),
  }),
  createProject: endpoint.post(paths.apiProjects, {
    summary: 'Create a project.',
    auth: true,
    body: S.Struct({ name: requiredString, slug: alphaDash }),
    success: ApiProject,
    status: 201,
    errors: { 409: SlugTaken },
  }),
  showProject: endpoint.get(paths.apiProject, { auth: true, success: ApiProject }),
  deleteProject: endpoint.delete(paths.apiProject, { auth: true }),
}
```

`action(endpoint, handler)` implements one. The handler receives `params`
(the path's placeholders), the signed-in user as `auth` when the contract has
`auth: true`, and the `query`, `body` and `headers` the contract declares,
already decoded. A body is read through its JSON form, as `call` sends it and
`openApi` describes it, so a `Date` arrives as its ISO string. A contract
with `auth: true` is answered 401 for a client that is not signed in, before
its input is read, so the requirement is declared once, where the API's
description reads it too. Input that does not decode is answered `422`,
with each invalid field's message in `errors`, before the handler runs. The
handler returns the success value, which the response encodes through the `success` schema,
so only the fields the schema declares leave the server, whatever the row
holds; an endpoint without `success` answers `204`. A failure the contract
declares is answered with its status in the error envelope, its `tag` the
failure's `_tag` and its fields in `body`. The package's own failures,
`notFound`, `forbidden`, `authorize()`'s 401 and the rest, are answered as
everywhere else, and every response of an endpoint is JSON, failures
included. `bound('project')` loads the model a placeholder in the contract's
path names, as in any action, and `responseHeader` adds a header such as a
created record's `Location`.

```ts
// src/actions/api/projects.ts
import { and, desc, eq, ilike } from 'drizzle-orm'
import { Effect } from 'effect'
import {
  action,
  bound,
  dbMutation,
  dbQuery,
  responseHeader,
} from '@popcomputer/web/effect'
import { href } from '@popcomputer/web/paths'
import { endpoints, SlugTaken } from '../../endpoints'
import { paths } from '../../paths'
import { projects } from '../../schema'

export const listProjects = action(endpoints.listProjects, ({ auth, query }) =>
  Effect.gen(function* () {
    const data = yield* dbQuery((db) =>
      db.select().from(projects)
        .where(and(eq(projects.userId, auth.user.id), query.q === null ? undefined : ilike(projects.name, `%${query.q}%`)))
        .orderBy(desc(projects.createdAt))
        .limit(Math.min(query.limit, 100))
    )

    return { data }
  })
)

export const createProject = action(endpoints.createProject, ({ auth, body }) =>
  Effect.gen(function* () {
    const [project] = yield* dbMutation((db) =>
      db.insert(projects)
        .values({ id: crypto.randomUUID(), name: body.name, slug: body.slug, userId: auth.user.id })
        .returning()
    ).pipe(
      Effect.catchTag('DatabaseConstraintViolation', (violation) =>
        Effect.fail(violation.constraint === 'unique'
          ? new SlugTaken({ slug: body.slug, message: `The slug ${body.slug} is taken.` })
          : violation)
      )
    )

    yield* responseHeader('Location', href(paths.apiProject, { project: project.id }))

    return project
  })
)

// The binding is ownedBy 'userId': another member's project is a 404.
export const showProject = action(endpoints.showProject, () => bound('project'))

export const deleteProject = action(endpoints.deleteProject, () =>
  Effect.gen(function* () {
    const project = yield* bound('project')

    yield* dbMutation((db) => db.delete(projects).where(eq(projects.id, project.id)))
  })
)
```

`routes.endpoint(action)` registers it on the method and path its contract
declares, with the route options other registrations take. A failure the
contract does not declare is an `unhandledErrors` type error at the
registration, as for any action, so the contract lists every failure a client
can tell apart. Group endpoints with `.provide(...)`, or under a prefix their
declared paths start with, `routes.prefix('/api/orgs/{org}')`.

```ts
// src/api-routes.ts
import { openApi } from '@popcomputer/web/endpoint'
import { action, json } from '@popcomputer/web/effect'
import { routes } from './app'
import { createProject, deleteProject, listProjects, showProject } from './actions/api/projects'
import { endpoints } from './endpoints'
import { paths } from './paths'

routes
  .endpoint(listProjects)
  .endpoint(createProject, { name: 'api.projects.store' })
  .endpoint(showProject)
  .endpoint(deleteProject, { purges: true })

const description = openApi(endpoints, {
  title: 'Projects API',
  version: '1',
  security: { session: { type: 'apiKey', in: 'cookie', name: 'better-auth.session_token' } },
})

routes.get(paths.apiDescription, action(json(description)))
```

`openApi(endpoints, info)` is an OpenAPI 3.1 document: each endpoint named
by its key, with its path and query parameters, headers, body, success and
declared failures; the `422` of an endpoint that reads input, the `401` of
one with `auth: true`, and the `404` of one whose path names a record. Give
`security` the ways a client signs in, as OpenAPI security schemes, and each
endpoint with `auth: true` lists them, so a generated client knows to send
the session cookie or a bearer token. A validator that accepts form posts as
well as JSON, such as `coercedNumber`, is described as the JSON a client
sends, a number, with the limits its checks add, such as a `maxLength`. Serve
it from a route, as above, or write it to a file in a build step.

---

<!-- docs/env.md -->

# Vars and secrets

An application declares its Worker's vars and secrets once, in
`src/env.ts`: each one's schema, whether it is a secret, whether the Worker
needs it, and how to make a value when nobody has to choose one. The
declaration types the bindings, each isolate checks its bindings against it
before serving, and scripts check it locally and before a deploy.

## Declaring them

The Quick start's `src/env.ts`:

```ts
import { Schema as S } from 'effect'
import { defineEnv, randomSecret, secret, variable, type EnvBindings } from '@popcomputer/web/env'

/** The Worker's vars and secrets, each declared once. */
export const env = defineEnv({
  DATABASE_URL: secret(),
  // Signs sessions: generated the first time, and replacing it signs everyone out.
  BETTER_AUTH_SECRET: secret(S.String.check(S.isMinLength(32)), { generate: randomSecret }),
  PAYMENT_WEBHOOK_SECRET: secret(S.String.check(S.isStartingWith('whsec_'))),
  // The origin Better Auth's emailed links name, never the host a request reached.
  APP_URL: variable(S.String),
  TIME_ZONE: variable(S.String, { optional: true }),
})

export type Bindings = EnvBindings<typeof env> & {
  KV: KVNamespace
  SIGN_IN_LIMITER: RateLimit
}

export type Env = { Bindings: Bindings }
```

- `secret(schema, options)` declares a secret: set on Cloudflare with
  `wrangler secret put NAME`, and in `.dev.vars` for the development server,
  never in `wrangler.jsonc`, where it would be committed. `secret()` alone
  is any non-empty string.
- `variable(schema, options)` declares a plain var, set in `wrangler.jsonc`'s
  `vars`. `variable()` alone is any string.
- `{ optional: true }` lets the Worker run without it. Every other var and
  secret is required.
- `{ generate }` makes a value for a secret nobody has to choose, such as a
  signing key: `randomSecret` makes 32 random bytes in base64. A script can
  then write one locally and upload one before the first deploy, as the
  demo's do. A secret without it must be set by hand, such as an API key
  another service issued.

The Worker receives every var and secret as a string, so each schema decodes
from one: `S.Literals(['development', 'production'])`, a string with checks,
or `S.FiniteFromString` for a number. A schema that does not, such as
`S.Number`, is a type error. `EnvBindings<typeof env>` is each value as the
Worker receives it, optional ones optional; the bindings that are not vars
or secrets, such as D1, KV or a rate limiter, stay in the type beside it, as
`wrangler.jsonc` declares them.

## Checked when an isolate starts

Pass the declaration to `setupWeb` as `env`, beside the rest of the
configuration, as the Quick start's
[`src/app.ts`](setup.md#3-configure-the-application-once-and-register-it)
does: `setupWeb(new Hono<Env>(), { ..., env })`.

Each isolate checks its bindings on its first request, Cron run or queue
batch, before the database or the auth client is made; a development server,
which gives each request bindings of its own, has each request's checked. A
var or secret that is missing, or that its schema refuses, fails every
request with `EnvInvalid`, which names each one and never a value:

```text
The Worker's vars and secrets do not match the env declaration:
- The secret PAYMENT_WEBHOOK_SECRET is missing.
- The secret BETTER_AUTH_SECRET is invalid: Expected a value with a length of at least 32.
```

The isolate logs each failure once, through Effect's logger, so the
Worker's logs name each problem in production too. The request answers 500
with the error page, code `WEB_CFG_306_ENV_INVALID`: as for any server
error, the page names the problems in development, and elsewhere says only
that the server failed. `routes.scheduled` and `routes.run` reject with
`EnvInvalid`, so the platform records the failed run, and `routes.queue`
leaves each message to retry. An empty secret counts as missing.

A test's bindings go through the same check, so `testEnv` takes every
required var and secret; a test of the failure leaves one out.

## Checking them before a deploy

`checkEnv(env, values)` checks any set of values against the declaration
and lists each problem, without its value, for a script that runs outside
the Worker. `@popcomputer/web/env` imports only `effect`, so a script reads
the same `src/env.ts` the Worker does:

```ts
// scripts/check-env.ts
import { readFileSync } from 'node:fs'
import { parseEnv } from 'node:util'
import { checkEnv, describeEnvProblem } from '@popcomputer/web/env'
import { env } from '../src/env'

const problems = checkEnv(env, parseEnv(readFileSync('.dev.vars', 'utf8')))

for (const problem of problems) console.error(describeEnvProblem(problem))
process.exitCode = problems.length === 0 ? 0 : 1
```

The development server reads `wrangler.jsonc`'s `vars` too, with `.dev.vars`
over them, so a script checking what it will see passes both.

Each problem is `{ name, kind, problem, expected }`: `kind` is `'secret'` or
`'variable'`, `problem` is `'missing'` or `'invalid'`, and `expected` says
what the schema wants. `env.entries` lists each var and secret with its
`kind`, `optional` and `generate`, for a script that sets them.

The demo's scripts use both, as
[its README](https://github.com/PatrickOgilvie/popcomputer-web-demo#vars-and-secrets)
shows:

- `bun run env:check` checks `.dev.vars` and the vars.
- `bun run env:check --remote` checks every required secret is on Cloudflare.
- `bun run secret NAME` checks a value before uploading it.
- `bun run deploy` refuses to deploy while a secret it cannot generate is
  missing, and uploads one it can.

## Reading them

Read a var or a secret in a service or an action with `config.string('NAME')`
or `config.redacted('KEY')` from `@popcomputer/web/effect`, as
[Application services](services.md) shows, and in `setupWeb`'s factories from
`c.env`, as the Quick start's `auth.client` reads `c.env.BETTER_AUTH_SECRET`.
Both are named by the bindings `EnvBindings` gives, so a name the
declaration does not hold is a type error.

---

<!-- docs/forms.md -->

# Forms

Each form's fields are a schema in a module the action and the page both
import. The action validates with it; the page imports it with `import type`,
so no server code reaches the bundle, and types its form with `FormInput`:

```ts
// src/forms.ts
import { Schema as S } from 'effect'
import { alphaDash, coercedDate, currentPassword, email, nullable, nullableString, requiredString } from '@popcomputer/web/schema'

export const CreateProject = S.Struct({
  name: requiredString,
  slug: alphaDash,
  description: nullableString,
})

export const RenameProject = S.Struct({ name: requiredString })

// The query the project list reads: a search, and where the page starts.
export const ProjectFilters = S.Struct({
  q: nullableString,
  beforeAt: nullable(coercedDate),
  beforeId: nullableString,
})

// A password signs in exactly as it was chosen: currentPassword never trims it.
export const SignIn = S.Struct({ email, password: currentPassword })
```

A form's fields derive from the schema its action validates them with:
`useForm<FormInput<typeof CreateProject>>({ ... })`, `FormInput` from
`@popcomputer/web/react`, so a renamed field is a type error in the form as
well as the action, and `const errors: FormErrors<typeof CreateProject> =
props.errors` types the errors the form reads by the same fields. Keep form
schemas in a module both sides import, `src/forms.ts`, and import them in
React with `import type`, so no server code reaches the browser.
The page below shows a form; [Pages and props](pages.md) shows the error page
and the client's page map.

A page reads its props, the shared props and `errors` from its declaration in
`src/pages.ts`, and its flash values from `usePage()`. A failed post comes
back to the page it was sent from, with the field errors in the form's
`errors`:

```tsx
// src/pages/Projects/Index.tsx
import { Link, useForm, usePage } from '@inertiajs/react'
import type { FormEvent } from 'react'
import { href } from '@popcomputer/web/paths'
import type { FormInput, WebPage } from '@popcomputer/web/react'
import { RenameProjectForm } from '../../components/RenameProjectForm'
import type { CreateProject } from '../../forms'
import { paths } from '../../paths'

const Index: WebPage<'Projects/Index'> = ({ projects, next }) => {
  const { flash } = usePage()
  const form = useForm<FormInput<typeof CreateProject>>({ name: '', slug: '', description: null })

  const submit = (event: FormEvent) => {
    event.preventDefault()
    form.post(paths.projects, { onSuccess: () => form.reset() })
  }

  return (
    <main>
      {flash.success && <p role="status">{flash.success}</p>}

      <ul>
        {projects.map((project) => (
          <li key={project.id}>
            <Link href={href(paths.project, { project: project.id })}>{project.name}</Link>
            <RenameProjectForm project={project} />
          </li>
        ))}
      </ul>
      {next && <Link href={href(paths.projects, {}, next)}>Older projects</Link>}

      <form onSubmit={submit}>
        <label>
          Name
          <input value={form.data.name} onChange={(event) => form.setData('name', event.target.value)} />
        </label>
        {form.errors.name && <p role="alert">{form.errors.name}</p>}

        <label>
          Slug
          <input value={form.data.slug} onChange={(event) => form.setData('slug', event.target.value)} />
        </label>
        {form.errors.slug && <p role="alert">{form.errors.slug}</p>}

        <label>
          Description
          <textarea
            value={form.data.description ?? ''}
            onChange={(event) => form.setData('description', event.target.value === '' ? null : event.target.value)}
          />
        </label>

        <button type="submit" disabled={form.processing}>Create project</button>
      </form>
    </main>
  )
}

export default Index
```

## Flash messages and failed forms

`yield* flash('success', 'Project saved.')` before any of them hands a value to
the next page the user sees, as Inertia's page `flash` field: the page a
redirect renders, or the page the same request renders.

A form submission that fails validation, whether in `validateRequest` or as a
`ValidationError` the action fails with, redirects back (303) to the page it
came from: the path of its same-origin `Referer`. A request without one, as a
test's that posts without visiting the form first, goes to the page its route
names with `form`, its placeholders filled from the route's own,
`routes.post(paths.bookSlot, bookSlot, { form: paths.slots })`; a route whose
path also has a page, such as `POST /slots` beside `GET /slots`, goes back to
that page without naming it; and any other goes to `/`. A
`ValidationError` with `redirectTo` goes to that page instead, such as a
wizard's earlier step. That page renders with all of its own props and the
field errors as `errors`; a form that names an Inertia error bag gets them
under its name.

Errors and flash values travel in a short-lived `HttpOnly` cookie that the
next page to render reads and clears. A request that only redirects, such as
a home page sending visitors to their dashboard, passes them on, so a failed
form whose `Referer` was missing still shows its errors where it lands. The
cookie is readable, not encrypted: never flash a secret, such as a new API key
shown once; render the page with it from the action instead.

A JSON client gets a 422 instead of the redirect. Invalid query parameters on
a page visit render the error page with 422, with the invalid fields as
`errors`; `readErrorPage(res)` from `@popcomputer/web/testing` reads it in a
test.

## Several forms on one page keep their errors apart

A failed form goes back to its page with the field errors in `errors`, keyed
by field. When the page holds several forms with a field of the same name,
such as the project list's create form and the rename form on each row, every
form would show the one that failed. An Inertia error bag keeps them apart:
the form names a bag when it submits, the request carries it as
`X-Inertia-Error-Bag`, and the errors come back under that name, which only
that form reads. The action needs nothing of its own; `validateRequest` and
`invalid` put the errors in the bag the request names:

```ts
// src/actions/projects/rename.ts
import { eq } from 'drizzle-orm'
import { Effect } from 'effect'
import { action, back, bound, dbMutation, flash, validateRequest } from '@popcomputer/web/effect'
import { RenameProject } from '../../forms'
import { paths } from '../../paths'
import { projects } from '../../schema'

export const renameProject = action(Effect.gen(function* () {
  // Its owner's only: the binding is ownedBy 'userId'.
  const project = yield* bound('project')
  const input = yield* validateRequest(RenameProject)

  yield* dbMutation((db) => db.update(projects).set({ name: input.name }).where(eq(projects.id, project.id)))
  yield* flash('success', 'Project renamed.')

  return yield* back(paths.projects)
}))
```

```ts
import { renameProject } from '../actions/projects/rename'

routes.put(paths.projectName, renameProject, { name: 'projects.rename', purges: true })
```

Each row's form names its own bag, so a rename that fails shows its error on
its own row, and the create form, which names none, shows only its own:

```tsx
// src/components/RenameProjectForm.tsx
import { useForm } from '@inertiajs/react'
import type { FormEvent } from 'react'
import { href } from '@popcomputer/web/paths'
import type { FormInput, PagePropsFor } from '@popcomputer/web/react'
import type { RenameProject } from '../forms'
import { paths } from '../paths'

type Project = PagePropsFor<'Projects/Index'>['projects'][number]

export function RenameProjectForm({ project }: { readonly project: Project }) {
  const form = useForm<FormInput<typeof RenameProject>>({ name: project.name })

  const submit = (event: FormEvent) => {
    event.preventDefault()
    form.put(href(paths.projectName, { project: project.id }), { errorBag: `rename-${project.id}` })
  }

  return (
    <form onSubmit={submit}>
      <input
        aria-label={`New name for ${project.name}`}
        value={form.data.name}
        onChange={(event) => form.setData('name', event.target.value)}
      />
      {form.errors.name && <p role="alert">{form.errors.name}</p>}
      <button type="submit" disabled={form.processing}>Rename</button>
    </form>
  )
}
```

The page's `errors` prop holds the bag as well, `errors['rename-project-1']`,
for a component that reads errors without `useForm`; a test reads it there
with `readPage`. Name one bag per form that can fail beside another, such as
approve and reject on each row of an inbox.

---

<!-- docs/fuzzing.md -->

# Fuzzing

`@popcomputer/web/fuzz` checks rules on inputs it generates, rather than on
the few a test writes by hand: any text a validator is given, any request a
browser or an attacker sends to the application's routes, any order of the
steps a lifecycle takes. Its pieces stand alone, on Effect's generators
(`effect/Arbitrary`), so an application's fuzz tests start from them and add
the application's own records and rules.

| Piece | What it gives |
| --- | --- |
| `fuzz(arbitrary, holds, { runs })` | runs a property: resolves when every case holds, rejects with the shrunk case, why it was refused and a replay token |
| `pick`, `oneOf`, `weighted`, `textOf`, `anyText`, `show` | generators that shrink toward their first choice, and a value shown with its invisible characters escaped |
| `fuzzRequest({ paths, params, people, forms })` | requests to the application's declared paths, from each person and a signed-out visitor |
| `sendFuzzRequest(app, sent, env)` | sends one through the application, as `app.request` does |
| `brokenPromises`, `leaks`, `strangerWrites`, `refusedWrites` | how an answer broke a rule, as a list empty when it kept them |
| `realmGuard()` | what a call wrote onto the realm's built-ins, such as `Object.prototype` |

Like `@popcomputer/web/testing`, it is for tests: `no-testing-in-production` reports it anywhere else.

## A property

A property returns why it refused an input, or nothing when it holds:

```ts
// src/slug.test.ts
import { test } from 'bun:test'
import { anyText, fuzz, fuzzTimeout, oneOf, show, textOf } from '@popcomputer/web/fuzz'

function slugOf(name: string): string {
  return name.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
}

// Names made of pieces that mean something to the rule, or any text at all.
const names = oneOf(textOf(['Apollo', ' ', '-', '--', 'É', ' ', '/', '..', '1']), anyText)

test('a slug is one URL segment of lowercase words', () => fuzz(names, (name) => {
  const slug = slugOf(name)

  return /^([a-z0-9]+(-[a-z0-9]+)*)?$/.test(slug) ? undefined : `${show(name)} gave ${show(slug)}`
}), fuzzTimeout)
```

`bun test` runs each property for 300 cases from a fixed seed, so the commit
gate gives the same answer each time; `{ runs }` lowers it for a property
whose cases are slow. Run many more from a random seed now and then:

```bash
FUZZ_RUNS=20000 FUZZ_SEED=random bun test
```

A failure prints the smallest case Effect's shrinking found, the reason the
property gave, and a replay token: `FUZZ_REPLAY='<token>' bun test -t
'<name>'` runs that case again. Once the bug is fixed, keep the case as a
plain test beside the property. As every test must (rule 12 of `AGENTS.md`),
a new property fails first on code with its bug planted.

## Requests to the application

`fuzzRequest` reads the application's paths and generates what reaches
them: any method, each path with each of its placeholders' values, the same
paths spelled another way (encoded, doubled slashes, dot segments, other
case), each form an action accepts with fields added, queries, bodies in
every shape and Content-Type, and headers from this site and others. Most
requests are ones a browser on the site sends, so they reach their actions;
the rest test the refusals.

```ts
// src/requests.test.ts
import { test } from 'bun:test'
import {
  brokenPromises,
  fuzz,
  fuzzRequest,
  fuzzTimeout,
  leaks,
  refusedWrites,
  sendFuzzRequest,
  strangerWrites,
} from '@popcomputer/web/fuzz'
import { signedIn, testEnv } from '@popcomputer/web/testing'
import app from './app'
import { paths } from './paths'
import './routes'
import { projects, user } from './schema'
import { testBindings } from './test-bindings'
import { freshDatabase } from './test-databases'

// Text only each person's private project holds: an answer that shows it to anyone else leaked it.
const canaries = { ada: 'canary-ada-7f3a', grace: 'canary-grace-91c2' }

const requests = fuzzRequest({
  paths,
  // Every placeholder in src/paths.ts, with each person's records, a public one and a missing one.
  params: {
    project: ['p-ada', 'p-grace', 'p-public', 'missing'],
    task: ['t-ada', 't-grace'],
    showcase: ['apollo', 'secret'],
    organization: ['acme', 'globex'],
    member: ['ada', 'grace'],
    provider: ['acme'],
  },
  people: ['ada', 'grace'],
  // A request each action accepts.
  forms: [
    { method: 'POST', path: paths.projects, fields: ['name=Apollo'] },
    { method: 'PUT', path: paths.project, fields: ['name=Renamed'] },
    { method: 'DELETE', path: paths.project, fields: [] },
  ],
})

test('any request keeps the rules', () => fuzz(requests, async (sent) => {
  const { db, close } = freshDatabase()

  try {
    await db.insert(user).values([
      { id: 'ada', name: 'Ada', email: 'ada@example.com' },
      { id: 'grace', name: 'Grace', email: 'grace@example.com' },
    ])
    await db.insert(projects).values([
      { id: 'p-ada', userId: 'ada', name: canaries.ada, slug: 'secret' },
      { id: 'p-grace', userId: 'grace', name: canaries.grace, slug: 'secret-too' },
      { id: 'p-public', userId: 'ada', name: 'Apollo', slug: 'apollo', isPublic: true },
    ])

    const rows = () => db.select({ id: projects.id, userId: projects.userId, name: projects.name, isPublic: projects.isPublic }).from(projects).orderBy(projects.id)
    const env = sent.person === null
      ? testEnv(testBindings, { database: db })
      : testEnv(signedIn({ id: sent.person }), testBindings, { database: db })
    const before = await rows()
    const answer = await sendFuzzRequest(app, sent, env)

    // A request fetch refuses to make never reaches the Worker.
    if (answer === undefined) return undefined

    const change = { before, after: await rows() }

    return [
      ...brokenPromises(sent, answer),
      ...leaks(sent, answer, canaries),
      ...strangerWrites(sent, change, { id: (row) => row.id, owner: (row) => row.userId }),
      ...refusedWrites(answer, change),
    ]
  } finally {
    await close()
  }
}, { runs: 200 }), fuzzTimeout)
```

`params` is typed by the paths: a path added to `src/paths.ts` with a new
placeholder is a type error here until the test names its values. Add a form
beside each new action, so its writes are generated with valid fields.

The rules each answer keeps:

- `brokenPromises`: the framework's, for any application. No request is
  answered 500; another site's write, by its Origin or else its Referer, is
  refused with a 403 unless it carries an Authorization no browser attaches
  by itself; a signed-in answer, or one that sets a cookie, is never kept by
  a shared cache; a JSON client gets each failure in the JSON envelope and is
  never sent to sign in; an Inertia visit that changes something is
  redirected with a 303. Give it `{ origin, signInPath }` when the
  application's differ from `http://localhost` and `/login`.
- `leaks`: no answer shows one person's canary to anyone else, in its body
  or its headers.
- `strangerWrites`: no row is changed or deleted by anyone but its owner,
  moved to another owner, or created for someone other than its sender.
- `refusedWrites`: a 4xx answer changed no rows.

## Building on it

The test is the application's to grow. Each rule is a function of the
request and the answer, so the application's own rules go beside them in
the list the property returns:

```ts
import type { FuzzRequest, RowsChange } from '@popcomputer/web/fuzz'

/** No request makes a private project public: only the visibility form may, and it is not generated. */
function madePublic(sent: FuzzRequest, change: RowsChange<{ readonly id: string; readonly isPublic: boolean }>): string[] {
  return change.after
    .filter((row) => row.isPublic && change.before.some((was) => was.id === row.id && !was.isPublic))
    .map((row) => `${sent.person ?? 'a visitor'} made ${row.id} public`)
}
```

`fuzzRequest` returns an `Arbitrary`, so `Arbitrary.map` changes what it
generates: an API's requests carry a key,
`Arbitrary.map(requests, (sent) => ({ ...sent, headers: { ...sent.headers, authorization: 'Bearer test-key' } }))`.
A person per role the application has (an owner, a member, a guest) lets
the rules see more.

## Steps over lasting state

State that lasts between requests, a cart, a balance, a sign-in count, is
fuzzed as sequences of steps: generate a list of steps, run each against the
application and against a small model of the rule, and compare them after
each step.

```ts
// src/cart.test.ts
import { test } from 'bun:test'
import { Arbitrary, Schema as S } from 'effect'
import { fuzz, fuzzTimeout, pick, show, weighted } from '@popcomputer/web/fuzz'
import { readJson, testBrowser, testEnv } from '@popcomputer/web/testing'
import app from './app'
import { testBindings } from './test-bindings'

const step = Arbitrary.all({
  act: weighted<'add' | 'remove' | 'checkout'>(['add', 3], ['remove', 2], ['checkout', 1]),
  product: pick(['tea', 'cake']),
  quantity: pick([1, 2, 5]),
})

const Cart = S.Record(S.String, S.Number)

test('the cart holds what its model holds', () => fuzz(Arbitrary.array(step, { maxLength: 12 }), async (steps) => {
  const browser = testBrowser(app, testEnv(testBindings))
  const model = new Map<string, number>()

  for (const [index, sent] of steps.entries()) {
    const held = model.get(sent.product) ?? 0

    if (sent.act === 'add') model.set(sent.product, held + sent.quantity)
    if (sent.act === 'remove') model.set(sent.product, Math.max(0, held - sent.quantity))
    if (sent.act === 'checkout') model.clear()

    await browser.request(`/cart/${sent.act}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ product: sent.product, quantity: sent.quantity }),
    })

    const cart = await readJson(await browser.request('/cart', { headers: { Accept: 'application/json' } }), Cart)
    const expected = [...model].filter(([, quantity]) => quantity > 0).sort()

    if (show(Object.entries(cart).sort()) !== show(expected)) {
      return `after step ${index + 1} of ${show(steps)}, the cart held ${show(cart)}`
    }
  }

  return undefined
}), fuzzTimeout)
```

The property returns the first step where the application and the model
disagree, with the steps before it, and Effect shrinks them to the fewest
that still disagree. Steps sent together, `Promise.all` over a step's requests, find
the races a sequence alone cannot. The package's own suite (`tests/fuzz` in
its repository) has one for each lifecycle `docs/state-machines.md` lists.

---

<!-- docs/guards.md -->

# Guards and roles

A guard decides whether the visitor may go on. `guard(...)` turns the Effect
that decides into a layer, provided to the routes it guards: it runs before
each action, may read the route's models with `bound()`, and turns the
visitor away by failing, as the action would have answered:

```ts
import { authorize, guard } from '@popcomputer/web/effect'

const RequireVerified = guard(authorize(({ user }) => user.emailVerified))

routes.provide(RequireVerified).get(paths.billing, showDashboard)
```

`guard` takes the Effect that decides; or a service and the Effect that
finds it, which the actions it guards then read; or a layer. Who may load a
record at all is its binding's to say, with `ownedBy`, `publicWhen` or
`public`, as [Route model binding](route-models.md#who-may-load-a-record)
shows: a guard decides it for a rule a column cannot state, such as
membership of an organization, whose binding says `guarded: true`. Such a
record loads only once a guard has read it and let the visitor in, and the
guard's read loads none of the records under it, such as the organization's
project, so a stranger the guard turns away gets its answer whether the
project exists or not. A layer that reads it for some other reason, such as
breadcrumbs, is no guard. A route whose records are asked for before a guard
has decided fails (`WEB_RTE_606_BINDING_ACCESS_INVALID`) before any lookup:
by a layer provided before the guard or built beside it, as `Layer.merge`
builds its layers, or by a guard that reads a record under the guarded one,
such as the project, before the organization's guard has decided. So
provide the guard on its own, before any other layer that reads a record.

The default page cache answers before any guard runs, so it caches no page
a guard decides for, however the guard was composed before it was provided,
nor one behind `routes.middleware(...)` or `prefixMiddleware(...)`. An access
check made any other way that reads something the page cache does not
track, as [Page caching](page-cache.md) lists, such as the time, needs
`cache: 'private'` on its routes.

An application that authenticates some other way, such as API keys, provides
its own user service through a layer that fails with `UnauthorizedError`:
`routes.provide(ApiKeyAuth)` runs it before the action, so every route
registered through it can read the service.

## A guard guards a group of routes

A rule every route in a group shares, such as "not once the project is
archived", is a guard provided to the group:

```ts
const OpenProject = guard(Effect.gen(function* () {
  const project = yield* bound('project')

  if (project.archivedAt !== null) return yield* forbidden('This project is archived.')
}))

routes.provide(OpenProject).put(paths.project, updateProject)
```

A guard that finds something the actions need, such as the visitor's
membership of an organization, provides it as a service, so every action in
the group, and a `shareProps` provided after it, reads it without querying
again:

```ts
class CurrentProject extends Context.Service<CurrentProject, {
  readonly project: typeof projects.$inferSelect
}>()('app/CurrentProject') {}

const OpenProject = guard(CurrentProject, Effect.gen(function* () {
  const project = yield* bound('project')

  if (project.archivedAt !== null) return yield* forbidden('This project is archived.')

  return CurrentProject.of({ project })
}))

routes.provide(OpenProject).get(paths.task, action(Effect.gen(function* () {
  const { project } = yield* CurrentProject

  return yield* render('Projects/Show', { project })
})))
```

## Roles belong to memberships, read by a guard

A role a user holds in one organization, such as admin, is not a field of the
user: the same user may be an admin of one organization and a member of
another, and a `role` column on the user table makes an admin anywhere an
admin everywhere. Keep the role on a membership row, one per user and
organization, and read it in a guard layer for the organization's routes.
The guard answers a visitor who is not a member with 404, so the
organization's existence stays private, and provides the membership as a
service, so actions and `shareProps` read it without querying again. The
organization's binding says so, `routeBinding(schema.organizations, { guarded: true })`,
and every route whose path names it is provided the guard. With Better
Auth's organization plugin, its `member` table is the membership row, read
the same way:

```ts
// src/memberships.ts
import { and, eq } from 'drizzle-orm'
import { Context, Effect } from 'effect'
import { authorize, bound, dbQuery, forbidden, guard, notFound } from '@popcomputer/web/effect'
import { memberships } from './schema'

export type Membership = typeof memberships.$inferSelect

export class CurrentMember extends Context.Service<CurrentMember, Membership>()('app/CurrentMember') {}

export const RequireMember = guard(CurrentMember, Effect.gen(function* () {
  const auth = yield* authorize()
  const organization = yield* bound('organization')
  const [membership] = yield* dbQuery((db) =>
    db.select().from(memberships).where(and(
      eq(memberships.organizationId, organization.id),
      eq(memberships.userId, auth.user.id)
    ))
  )

  if (membership === undefined) return yield* notFound('Organization')

  return CurrentMember.of(membership)
}))

// A member who can see the organization but lacks the role gets a 403.
export const requireRole = (...roles: ReadonlyArray<Membership['role']>) =>
  Effect.gen(function* () {
    const member = yield* CurrentMember

    if (!roles.includes(member.role)) return yield* forbidden('Your role in this organization does not allow that.')

    return member
  })
```

On Postgres through Hyperdrive, query caching is on by default: a read can be
answered from Hyperdrive's cache for up to a minute without asking the
database, so a membership just removed, or a role just lowered, still lets
its member through. Read memberships, roles and sessions through a Hyperdrive
configuration with caching disabled, as Cloudflare's
[query caching](https://developers.cloudflare.com/hyperdrive/concepts/query-caching/)
page recommends for them. D1 has no such cache.

A permission names what a route does rather than who may do it, so what
each role may do is one table, and a new role is one row:

```ts
// src/permissions.ts
import { Effect } from 'effect'
import { forbidden } from '@popcomputer/web/effect'
import { CurrentMember, type Membership } from './memberships'

export type Permission = 'members.invite' | 'members.role' | 'projects.delete'

const permissions: Readonly<Record<Membership['role'], ReadonlyArray<Permission>>> = {
  owner: ['members.invite', 'members.role', 'projects.delete'],
  admin: ['members.invite', 'members.role'],
  member: [],
}

export const can = (permission: Permission) =>
  Effect.gen(function* () {
    const member = yield* CurrentMember

    if (!permissions[member.role].includes(permission)) return yield* forbidden('Your role in this organization does not allow that.')

    return member
  })
```

An action states the role or permission it needs, `yield* can('members.role')`,
so the check travels with it wherever it is registered. The member it changes is a route model
too: `{member:userId}` binds the organization's membership of the user the
path names, so a member of another organization is a 404, and the write is
scoped by the bound row rather than by anything the request sends:

```ts
// src/actions/organizations/change-role.ts
import { and, eq, ne } from 'drizzle-orm'
import { Effect, Schema as S } from 'effect'
import { action, back, bound, dbMutation, flash, forbidden, validateRequest } from '@popcomputer/web/effect'
import { paths } from '../../paths'
import { can } from '../../permissions'
import { memberships } from '../../schema'

const ChangeRole = S.Struct({ role: S.Literals(['admin', 'member']) })

export const changeRole = action(Effect.gen(function* () {
  yield* can('members.role')
  const organization = yield* bound('organization')
  const member = yield* bound('member')
  const input = yield* validateRequest(ChangeRole)

  const [changed] = yield* dbMutation((db) =>
    db.update(memberships)
      .set({ role: input.role })
      .where(and(
        eq(memberships.organizationId, member.organizationId),
        eq(memberships.userId, member.userId),
        // An owner's role changes only by transferring ownership.
        ne(memberships.role, 'owner')
      ))
      .returning()
  )

  if (changed === undefined) return yield* forbidden("An owner's role changes only by transferring ownership.")

  yield* flash('success', 'Role changed.')

  return yield* back(paths.organizationMembers, { organization: organization.slug })
}))
```

The organization's routes share its path prefix and the guard, so they are
grouped under `routes.prefix(...)`. Each is registered with its whole
declared path, which must start with the prefix:

```ts
import { changeRole } from '../actions/organizations/change-role'
import { RequireMember } from '../memberships'

routes
  .prefix('/orgs/{organization:slug}')
  .provide(RequireMember)
  .put(paths.organizationMember, changeRole, { name: 'organizations.members.role' })
```

`changeRole` reads `CurrentMember` through `can`, which only `RequireMember`
provides, so registering it without the guard is a `missingServices` type
error, and the guard reads `bound('organization')`, so its routes need
`{organization}` in their path or prefix. A group whose every route needs
one permission is given it as a guard after the membership guard,
`.provide(RequireMember).provide(guard(can('projects.delete')))`, which turns
a member without it away with a 403 before any of its actions runs. A membership's role is an enum column, `text('role', { enum:
['owner', 'admin', 'member'] })`, so a misspelled role is a type error in
`requireRole`, in the table of permissions and in the update. A test seeds a membership for the user it
signs in with `signedIn`, and checks a stranger gets 404 and a member 403.

---

<!-- docs/installation.md -->

# Installation

To start from a complete application, create one from the
[demo](https://github.com/PatrickOgilvie/popcomputer-web-demo): React pages
from a Cloudflare Worker, with D1, Better Auth and tests, ready to deploy:

```bash
bun create PatrickOgilvie/popcomputer-web-demo my-app
```

It needs Node.js 22 or later (better 24, which portless is built for), Bun,
and portless running as a service, which the demo's README sets up
[once per computer](https://github.com/PatrickOgilvie/popcomputer-web-demo#once-per-computer).
Then `bun run dev` in `my-app` serves it at `https://my-app.localhost`.

To add the package to an application of your own:

```bash
bun add @popcomputer/web effect hono
```

Add only the optional integrations your application uses:

```bash
bun add better-auth                         # Better Auth integration
bun add drizzle-orm                         # Drizzle route model binding
bun add @inertiajs/react react react-dom    # React client
```

And the tools the documentation's setup uses while developing:

```bash
bun add -d drizzle-kit                      # migrations from the Drizzle schema
bun add -d @cloudflare/workers-types        # types for the Worker's bindings
bun add -d @electric-sql/pglite             # tests on Postgres, in process
bun add -d miniflare                        # tests on Cloudflare D1, in process
```

Applications built while developing the package used drizzle-kit
`^0.31.11`, `@cloudflare/workers-types` `^5.20261013.1`, PGlite `^0.5.9` and
Miniflare `^4.20260730.0`.

The application's `tsconfig.json` needs the DOM library and JSX for its React
pages, and Cloudflare's types for its bindings (`bun init` writes neither):

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM"],
    "jsx": "react-jsx",
    "types": ["bun", "@cloudflare/workers-types"],
    "strict": true,
    "skipLibCheck": true
  }
}
```

The examples read a row from `.returning()` as `const [project] = ...`; with
`noUncheckedIndexedAccess` on, guard the row before using it.

The package's lint rules check what types cannot see, such as an update
without a `where`, a transaction that calls the network, or SQL built from a
string. They run in [Oxlint](https://oxc.rs), with nothing to configure
beyond turning them on:

```bash
bun add -d oxlint
```

```ts
// oxlint.config.ts
import { defineConfig } from 'oxlint'
import { webLint } from '@popcomputer/web/lint'

export default defineConfig(webLint())
```

`bunx oxlint` then reports each mistake with the API to use instead and why;
[Lint rules](lint-rules.md) lists them. Oxlint loads `oxlint.config.ts` as an
ES module: give `package.json` `"type": "module"`, or Node warns
`MODULE_TYPELESS_PACKAGE_JSON` on every run.

An application whose Worker runs inside Vite's dev server, as the demo's
`bun run dev` runs it with Cloudflare's Vite plugin, gives Vite the package's
plugin beside `cloudflare()`:

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { reloadWorkerModules } from '@popcomputer/web/vite'

export default defineConfig({
  plugins: [reloadWorkerModules() /* , cloudflare() from @cloudflare/vite-plugin */],
})
```

The routes register once, when `src/routes.ts` runs. Vite's hot update runs
again only the modules that import the file that changed, so without the
plugin an edit to an action or to `src/routes.ts` runs `src/routes.ts` again on
the routes already loaded, and every request fails with `GET /login is
registered twice` until the dev server restarts. The plugin runs all the
Worker's modules again instead, on a new app. The Worker's main module, such
as `src/worker.ts`, and the browser's modules keep Vite's hot updates.

Coding agents should read `node_modules/@popcomputer/web/AGENTS.md`, a short
rulebook naming the one API to use for each task, and the files in
`node_modules/@popcomputer/web/docs/` as a task needs them:
[Which API for which task](which-api.md) names the file for each. Reference
the rulebook from the application's own `AGENTS.md` or `CLAUDE.md`. The same
rules ship as a Claude skill in `skills/popcomputer-web/SKILL.md`; copy that
directory into `~/.claude/skills/` or a project's `.claude/skills/`.
[The agent fence](agent-fence.md) makes the rules that matter most checks
an agent cannot skip: the commit gate, the command hook and the debt report.

Effect and Hono are peer dependencies so an application owns one Effect runtime
and one Hono type identity. `better-auth` and `drizzle-orm` are optional peers:
an app without them still bundles for Cloudflare Workers. Route model binding
loads `drizzle-orm` when a bound route runs and reports a configuration error
if it isn't installed.
The package supports Effect 4 (`^4.0.0`, tested with 4.0.5), Hono 4.13.5 or
later 4.x (tested with 4.13.13), Better Auth 1.7 from 1.7.7 (tested with
1.7.10), and Drizzle ORM
0.45.2 or later 0.x (tested with 0.45.4). Each floor is the first release
with the security fixes for the parts this package uses: Hono's cookies and
body parsing, Drizzle's identifiers, Better Auth's redirects and tokens. Hono 5 and Drizzle 1.0 are not
supported yet: both change APIs this package uses. Better Auth's range is one
minor version, the one the package's Better Auth tests pass against: they
drive its sign-in, sessions, two-factor, magic links, OAuth providers,
organizations, bearer tokens and admin plugins through an application, and
check [Better Auth's tables](auth-tables.md) against what Better Auth needs. A
release supports a newer Better Auth once they pass against it.

---

<!-- docs/json.md -->

# JSON clients

A JSON client gets every failure in one envelope, whatever its status. A
request is a JSON client when it asks for JSON or sends a JSON body, or when
it asks for no HTML while sending an `Accept` header, as `fetch` does with
`*/*`, or an `Authorization` header, as an API client with a bearer token
does. So is a request whose User-Agent names a command-line or AI client
(`curl`, `claude`, `CLI`), such as an agent checking a page with `curl`.
Browsers ask for HTML on every visit and form post, so they get pages,
a signed-out visitor goes to sign in, and a failed form goes back to the
form; a signed-out JSON client gets a 401 instead. An Inertia visit
(`X-Inertia: true`) always gets Inertia's page protocol, whatever its
User-Agent or `Accept`. `prefersJson` and `jsonOrRender` decide the same way.

```json
{
  "code": "WEB_VAL_004_SCHEMA_MISMATCH",
  "tag": "ValidationError",
  "message": "This field is required",
  "httpStatus": 422,
  "errors": { "name": "This field is required" }
}
```

An API whose clients may send neither header, such as a scanner that forgot
its key, registers its routes on `routes.jsonApi()`, with their declared
paths, `routes.jsonApi().provide(ApiKeyAuth).get(paths.apiInvoices, listInvoices)`:
every request to them is a JSON client. An API that rejects query parameters
it does not declare passes `validateRequest(Query, { request: { order:
['query'] }, parseOptions: { onExcessProperty: 'error' } })`; reading only
the query keeps the route's own parameters from counting as excess.

## JSON responses declared by a schema

A JSON API declares each endpoint as a contract, as
[JSON endpoints](endpoints.md) shows, and its actions return values the
contract encodes. An ordinary action that answers JSON, such as a page's
`jsonOrRender`, declares its response as an Effect Schema and answers with
`json(Schema, value)`: the value is checked against the schema and encoded
through its JSON form, so a `Date` leaves as an ISO string. A test reads it
back with `readJson(res, Schema)` from `@popcomputer/web/testing`, and a
client decodes it with the same schema,
`S.decodeUnknownSync(S.toCodecJson(Schema))(await res.json())`, so the shape
is declared once. `Jsonify<typeof Schema.Type>` from
`@popcomputer/web/effect` types a JSON response as React reads it.

A schema a client imports is bundled with it. Declare a response schema that
a separate client decodes, such as a CLI's or an SDK's, apart from the
Drizzle tables, unlike a page schema, which React reads only as a type: read
its columns with `columnsOf(table, Schema)` and answer with
`json(Schema, rows)`, where a field whose column changes type fails to
type-check. The same holds for a page answered with `jsonOrRender` that such
a client decodes.

## Failures a client reads

The envelope's `errors` names each invalid field's message, as a form's page
receives them. `ErrorResponse` from `@popcomputer/web/schema` is the
envelope's schema, which imports only `effect`, so a client decodes a failure
with it; `readError(res)` from `@popcomputer/web/testing` reads it in a test.

An `HttpError` with a body adds it as `body`. A body a client reads is
declared by a schema, as a JSON response is:
`httpError(409, 'Some lines are short of stock.', ShortOfStock, { lines })`
checks and encodes it, a test reads it with `readError(res, ShortOfStock)`,
and a client decodes the whole failure with `errorResponseWith(ShortOfStock)`.
A body without a schema,
`httpError(409, 'Already checked in.', { code: 'ticket_already_used' })`,
reaches the client as
`{ ..., "httpStatus": 409, "body": { "code": "ticket_already_used" } }`.

Answer a record the client may not see with `notFound(...)`, which is what a
missing bound record answers, rather than an `httpError(404, ...)` with a body
of its own, so a client cannot tell which ids exist. Production replaces the
message of a 5xx or an internal failure with a generic one, and gives every
404 the same message: a 404 whose message a page shows carries it in a body,
`httpError(404, message, Schema, { message })`, which production keeps. Test
the envelope a client receives with `ENVIRONMENT: 'production'` in the test
bindings.

## Calling an endpoint

`call(endpoint, input, options)` sends a request built from the contract and
reads the answer: `{ ok: true, value }` with the success decoded, so dates
are `Date`s again, or `{ ok: false, error }`, where `error` is a declared
failure, decoded as the failure itself, or an `EndpointFailure` holding the
envelope, such as a 422's `errors`. Both narrow on `_tag`. In the browser it
uses `fetch` and the page's origin; a test passes the application as `fetch`,
so the test reads as a client does:

```ts
// src/api.test.ts
import { expect, test } from 'bun:test'
import { call } from '@popcomputer/web/endpoint'
import { signedIn, testEnv } from '@popcomputer/web/testing'
import app from './app'
import './api-routes'
import { endpoints } from './endpoints'
import { testBindings } from './test-bindings'

const as = (id: string) => ({
  fetch: (request: Request) => app.request(request, undefined, testEnv(signedIn({ id }), testBindings)),
})

test('a slug is taken once', async () => {
  const created = await call(endpoints.createProject, { body: { name: 'Launch', slug: 'launch' } }, as('user-1'))
  const again = await call(endpoints.createProject, { body: { name: 'Again', slug: 'launch' } }, as('user-1'))

  expect(created.ok && created.value.slug).toBe('launch')
  expect(!again.ok && again.error._tag).toBe('SlugTaken')
})

test("another member's project is not found", async () => {
  const shown = await call(endpoints.showProject, { params: { project: 'project-1' } }, as('user-2'))

  expect(shown.status).toBe(404)
})
```

The input is encoded through the contract's schemas without their checks, so
a form that calls an endpoint shows the server's messages for each invalid
field. A page's form posts stay ordinary actions with `validateRequest`; an
endpoint serves a client that reads JSON, such as a search box, a mobile app
or another service.

---

<!-- docs/lint-rules.md -->

# Lint rules

The type checker reports what the framework can see in types: a service the
setup does not provide, a failure an action leaves unhandled, a path that is
not declared. The rules in `@popcomputer/web/lint` report the mistakes types
cannot see, the ones a reviewer has to know to look for. They apply where a
file uses the framework: the action rules to files that import `action`, the
database rules inside `dbQuery`, `dbMutation`, `dbTransaction` and `dbBatch`,
the binding rule to `setupWeb`'s `bindings` and `routeBinding`, and the
rules about where code runs by where a file sits: a test, a script, a page,
a component. The examples in `docs/`, the README and `AGENTS.md` pass them.

| Rule | Reports | Use instead |
| --- | --- | --- |
| `no-unscoped-write` | An `update` or `delete` with no `.where(...)`, which changes every row | `.where(...)` scoped by the bound model or the signed-in user |
| `no-write-in-db-query` | An `insert`, `update` or `delete` in `dbQuery` (fixable) | `dbMutation`, whose failures are typed |
| `no-external-work-in-transaction` | `fetch`, `background`, the cache, `Effect.sleep` or `Effect.promise` inside `dbTransaction` | The call before or after the transaction |
| `no-sql-interpolation` | `sql.raw(text)` or SQL built from a string with values in it | Drizzle's builder, or `` sql`... ${value}` ``, which binds values |
| `no-database-service-in-action` | `DatabaseService` or `$client` in an action module | `dbQuery`, `dbMutation`, `dbTransaction`, `dbBatch` |
| `no-raw-request-input` | `RequestService`'s `json()`, `parseBody()`, `query()` or `params()` | `validateRequest(Schema)`, or the endpoint's contract |
| `no-hono-context-in-action` | Hono's `c.req`, `c.env` or `c.json` inside an action | `validateRequest`, `config.string`, response helpers |
| `no-effect-runner-in-action` | `Effect.runPromise` and the other runners | `yield*` the Effect |
| `no-catch-all-in-action` | `Effect.catch`, `orDie`, `ignore` and the like over the database, `authorize()`, `bound()` or `validateRequest`, called or piped | `Effect.catchTag` for the failures the action answers |
| `no-raw-response-in-action` | `new Response(...)` | `json`, `text`, `file` (which serves uploads with `nosniff`), `noContent` |
| `no-provision-in-action` | `Effect.provide` in an action module | `web.services(...)`, or `routes.provide(layer)` |
| `require-background` | `waitUntil(...)` | `background('name', effect)` |
| `no-validation-in-endpoint` | `validateRequest` or `json` in an endpoint's action | The handler's argument, and the returned value |
| `require-binding-access` | A binding that does not say who may load its record: a bare table, or `routeBinding` without `ownedBy`, `publicWhen`, `public`, `guarded` or `scope`; or an option, or a `publicWhen` value, written `undefined` | `routeBinding(schema.projects, { ownedBy: 'userId' })`, or the option that says who may; `publicWhen: { isPublic: true }` |
| `prefer-checked-config` | Effect's `Config.String('NAME')` and its siblings in an application of the framework | `config.string('NAME')`, which checks the name against the Worker's bindings |
| `no-auth-api-in-action` | `auth.api.signInEmail(...)` and Better Auth's other endpoints called from an action, which skips its rate limits | `betterAuthRedirect('signInEmail', { body }, ...)` or `betterAuthCall(...)` |
| `no-floating-effect` | A framework call that builds an Effect, written as a statement, so nothing runs it: `dbMutation(...)`, `flash(...)`, `redirect(...)`, `cart.set(...)`, `Effect.log(...)`; and `yield` without `*` | `yield* dbMutation(...)`, or `return` it |
| `no-module-level-mutable-state` | A module-scope `let` or `var`, or a module-scope `Map`, `Set` or array a function changes, outside tests, configuration, scripts, pages and components: a Worker's isolate shares it with every request, so one visitor's data can reach another's | Values inside the action, `web.services({ app })` for a service built once, `cache(key, effect, schema, { ttl, tags })` for data kept across requests |
| `no-testing-in-production` | An import of `@popcomputer/web/testing` (whose `signedIn` signs a request in with no session) or `@popcomputer/web/fuzz` from a file that is not a test | The helpers in tests only; `authorize()` or `currentUser` in the application |
| `no-server-imports-in-pages` | A page or component (under `src/pages/`, `src/components/` or `src/layouts/`, or importing `@popcomputer/web/react`) importing server code: `@popcomputer/web`, `/effect`, `/auth`, `/env`, `/cache`, `/drizzle`, `drizzle-orm`, the Drizzle schema, the env module or an action | Props declared in `src/pages.ts`, `href` from `@popcomputer/web/paths`, and `import type` for types |
| `require-disable-reason` | A comment turning off one of these rules, or every rule, with no reason after `--` | `// oxlint-disable-next-line popcomputer-web/no-sql-interpolation -- the values are constants`, or the API the rule names |
| `explain-security-loosening` (a warning) | A setting that weakens a protection the framework gives: `routeBinding(table, { public: true })`, `betterAuthHandler({ settable: [...] })`, `verifyOrigin`'s `allowedOrigins` or `verifyOrigin: false`, `security.headers: false`, a `bodyLimit` over 1 MiB, `history: { encrypt: false }` or `encryptHistory: false`, and `betterAuth` with password sign-in but no `requireEmailVerification: true`, or with `autoSignInAfterVerification: true` | The default, or a reasoned disable comment where it is set, which puts the choice before a reviewer |

## What each rule sees

The rules read one file's syntax. They follow its imports and the names it
declares, but resolve no module and run no type checker, so each has limits.
A limit listed here is a known boundary of the rule, not a way around it.
The notes cover six of the rules; the others see the calls their row names,
written in the file, and nothing a helper in another module does.

- `no-floating-effect`. Covers: an expression statement, anywhere in a file,
  that calls one of the framework's Effect constructors (the database
  operations, `authorize`, `bound`, `validateRequest`, the response helpers,
  `flash`, `share`, `responseHeader`, `purgeCache`, `background`,
  `betterAuthCall`, the data cache's calls) or any of Effect's own functions
  but its runners, through `.pipe(...)`, `void`, `&&`, `?:` and commas; a
  cookie declaration's `.set(...)`, `.read` and `.clear`, whether declared in
  the file or imported under a name ending in `Cookie`; and `yield` without
  `*` before any of them. Does not see: an Effect the application's own
  function returns (`notifyOwner(project)` as a statement), one assigned and
  never yielded, one built in an array or an object, a cookie imported under
  another name, or the framework imported through a file that re-exports it.
  The Effect language service sees all of these by type.
- `no-module-level-mutable-state`. Covers: `let` and `export let` at module
  scope, `var` anywhere outside a function, and a module-scope `const` holding
  a `new Map()`, `new Set()` or an array literal that a function changes
  (`.set`, `.add`, `.push`, `.delete` and the other mutating methods, or an
  assignment to one of its elements), in every file but tests (`*.test.ts`,
  `*.spec.ts`, `test-*.ts`, anything under `test/`, `tests/` or
  `__tests__/`, and the file `bunfig.toml`'s `[test] preload` names), tools'
  configuration (`*.config.ts`), declarations (`*.d.ts`), `scripts/`, and
  pages and components (under `src/pages/`, `src/components/` or
  `src/layouts/`, or importing `@popcomputer/web/react`), which run in one
  visitor's browser. A collection filled as the module loads and only read
  after is the same for every visitor, and passes. Does not see: an object
  literal whose properties a function changes, a class's static fields,
  state another module holds and this one changes, or a collection built by
  a function call (`const seen = makeCache()`). It counts as the collection
  a local name that shadows one inside a function, and as the Worker's a
  browser module in another folder that does not import
  `@popcomputer/web/react`, such as a client entry: say why on its disable
  comment.
- `no-testing-in-production`. Covers: `import`, `export ... from`,
  `import('...')` and `require('...')` of `@popcomputer/web/testing` or
  `@popcomputer/web/fuzz` with the source written as a string, in any file
  that is not a test as `no-module-level-mutable-state` counts them.
  `import type` passes: the build erases it. Does not see: a production module importing a test
  helper that imports the testing helpers (`src/app.ts` importing
  `./test-db`), a source built at runtime, or a re-export of the helpers
  under another package's name.
- `no-server-imports-in-pages`. Covers: in a file under `src/pages/`; one
  under `src/components/` or `src/layouts/`, at any depth, that is not a
  test, since pages import their components from there and a component's
  test runs in Bun; or one that imports `@popcomputer/web/react`
  (`import type` included), an import, re-export, `import()` or
  `require()` of the framework's server entrypoints
  (`@popcomputer/web`, `/effect`, `/auth`, `/env`, `/cache`, `/drizzle`),
  `drizzle-orm`, or the application's own server modules by name, relative
  or through a `@/` or `~/` alias: a file named `schema`, `auth-schema`,
  `env`, `db`, `auth`, `app`, `routes` or `worker`, or one in an `actions/`,
  `schema/` or `db/` folder. `import type` and `import { type X }` pass, so
  a form reads its action's schema as `FormInput<typeof Schema>`;
  `@popcomputer/web/paths`, `/schema` and `/endpoint` pass. Does not see: a
  component in another folder (`src/ui/`, `src/hooks/`) that does not import
  `@popcomputer/web/react`, a server module under another name (`./data`), a
  module that imports server code itself (`../forms` importing `../db`),
  other path aliases, or server-only packages besides Drizzle, such as
  `better-auth` itself.
- `require-disable-reason`. Covers: every `oxlint-disable`,
  `oxlint-disable-line`, `oxlint-disable-next-line` and `eslint-disable*`
  comment, line or block, that names a `popcomputer-web/` rule, or names no
  rule and so turns off all of them, without words after `--` (two or more
  dashes, with a space on each side). It reads the directives as Oxlint and
  ESLint parse them, `sourceCode.getDisableDirectives()`, which find the
  reason and require none. A single dash, a bare `--` or `-- .` gives no
  reason. Does not see: a comment that turns this rule off, which hides its
  own report, so a file-wide `/* oxlint-disable */` with no rules, as
  generated files carry, passes; whether the reason is true; and a rule
  turned off in the configuration, `webLint({ 'no-sql-interpolation': 'off'
  })` or `ignorePatterns`.
- `explain-security-loosening`. Covers: in a file that imports
  `@popcomputer/web`, `/effect` or `/auth`, the settings above written as
  literals: `public: true` in `routeBinding`'s options or a binding object
  with a `schema`; a `settable` other than `[]` in `betterAuthHandler`'s
  options; `allowedOrigins` other than `[]` under any `verifyOrigin` key or
  in `verifyOrigin(...)`; `verifyOrigin: false`; `headers: false` under
  `security`; any `bodyLimit` whose value is a number over 1 MiB, written
  as a literal, arithmetic on literals or a `const` holding one;
  `encrypt: false` under `history` and `encryptHistory: false`; and, in
  `betterAuth({ ... })` from `better-auth`, `emailAndPassword` with
  `enabled: true` and no `requireEmailVerification: true`, or
  `emailVerification.autoSignInAfterVerification: true`. Does not see: a
  setting built at runtime or spread in from another object, a `bodyLimit`
  read from a binding, or `betterAuth` called through a wrapper or with its
  options in a variable.

## The Effect language service

The language service's `floatingEffect` diagnostic finds every Effect that is
neither yielded nor assigned, by its type, so it sees the application's own
functions the lint rule cannot. It reaches `tsc` only once `tsc` is patched:
a `tsconfig.json` plugin runs in the editor's language server alone, and an
unpatched `tsc --noEmit` passes a floating Effect with exit code 0. On
TypeScript 7 the service ships as `@effect/tsgo`:

```bash
bun add -d @effect/tsgo
```

Name the plugin in `tsconfig.json` (its name stays `@effect/language-service`)
and patch the installed TypeScript on every install:

```json
{
  "compilerOptions": {
    "plugins": [{ "name": "@effect/language-service" }]
  }
}
```

```json
{
  "scripts": { "prepare": "effect-tsgo patch" }
}
```

`tsc --noEmit` then fails with `effect(floatingEffect)` on the statement, in
`.ts` and `.tsx` files alike: `floatingEffect` is an error by default, and an
Effect error sets `tsc`'s exit code unless the plugin's
`ignoreEffectErrorsInTscExitCode` says otherwise. It also reports `yield`
without `*` (`missingStarInYieldEffectGen`). `bun install` runs `prepare`;
an install with scripts turned off, such as `bun install --ignore-scripts` in
a CI job, leaves `tsc` unpatched, passing floating Effects again. On
TypeScript 5 or 6 the package is `@effect/language-service`, with
`"prepare": "effect-language-service patch"`.

## Turning a rule off

A line that breaks a rule on purpose says why, as
`// oxlint-disable-next-line popcomputer-web/no-sql-interpolation -- the values are constants`,
and `require-disable-reason` reports one that does not.
`explain-security-loosening` is a warning: a setting it reports may be
meant, and the reasoned disable comment is how it is acknowledged, so the
next reader sees why the protection is weaker there.
`webLint({ 'no-catch-all-in-action': 'warn' })` changes a rule's severity, and
`webLint()` spreads into a larger configuration,
`defineConfig({ ...webLint(), ignorePatterns: ['dist'] })`.

---

<!-- docs/lower-level.md -->

# Lower-level composition

Most applications should use `setupWeb`. The lower-level APIs are available
when another composition root owns part of the middleware stack:

```ts
// src/manual-app.ts
import { Hono } from 'hono'
import {
  createTemplate,
  createVersion,
  web,
  webContext,
  webDefaults,
  webServices,
} from '@popcomputer/web'
import { effectBridge } from '@popcomputer/web/effect'
import manifest from '../dist/manifest.json'
import { createDb } from './db'
import type { Bindings } from './env'

type Env = { Bindings: Bindings }

const app = new Hono<Env>()

app.use('*', webDefaults())
app.use('*', web({
  version: createVersion(manifest),
  render: createTemplate({ title: 'Projects' }),
}))
app.use('*', webServices<Env>((c) => ({
  db: createDb(c.env.DATABASE_URL),
})))
app.use('*', effectBridge())

app.use('/admin/*', async (c, next) => {
  const { authUser } = webContext(c)
  if (!authUser) return c.redirect('/login')
  await next()
})
```

`webDefaults()` comes first, so it sees every response: it is the policy
`setupWeb` installs, as three middleware also exported on their own.
`securityHeaders()` sends `nosniff`, a `Referrer-Policy` and refuses framing;
`privateByDefault()` marks a response that states no `Cache-Control` as
`private, no-cache`, or `no-store` when it is signed in or sets a cookie, so
Workers Cache never hands a page rendered for one visitor to the next; and
`verifyOrigin()` refuses a state-changing request from another site with a
JSON 403. It takes `setupWeb`'s `security` options:
`webDefaults({ verifyOrigin: { allowedOrigins: ['myapp://'] } })`. Without
`privateByDefault()` around it, `web()` gives what it answers the same
`Cache-Control` itself, so a stack composed before `webDefaults()` existed
keeps its pages out of shared caches too; it still lacks the headers and the
origin check.

Add `pageCache({ version })` after `webDefaults()` and before `webServices()`
to keep the default page cache; on a hit it answers before database and auth
setup.

Register routes with `effectRoutes(app)`. It cannot see which services the
hand-written middleware provides, so it accepts actions that use any framework
service and reports an unconfigured one at runtime, as a configuration error.
Pass extra service types it should accept as `effectRoutes<Env, Mailer>(app)`.

Plain Hono handlers can render through `c.var.web`:

```ts
app.get('/', (c) => c.var.web.render('Home'))
```

Effect actions normally use the higher-level `render` helper. The underlying
service is available as `PageService` when direct composition is useful.

---

<!-- docs/page-cache.md -->

# Page caching

Pages are cached at Cloudflare's edge by default. `setupWeb` serves a page from
Cloudflare's Cache API, skipping database, auth and rendering work, when
producing it read nothing request-specific. A page becomes dynamic, and renders
on every request, when it reads:

- the database, through `dbQuery` or any other use of `DatabaseService`,
  whether its client reaches the database through a binding or a
  connection string;
- a binding on `c.env` (D1, KV, R2, Durable Objects, service bindings, AI,
  Hyperdrive);
- a request header, the raw request or request state, through
  `RequestService` or `RequestStateService`, or through the context a
  `web.services` request callback, `routes.middleware(...)`,
  `prefixMiddleware(...)` or the `render` template receives;
- a route model binding.

Cached pages are keyed by deploy. Bind the version metadata so each deploy
starts from an empty cache:

```jsonc
// wrangler.jsonc
"version_metadata": { "binding": "CF_VERSION_METADATA" }
```

Without it, pages are keyed by the asset version and expire after five minutes,
so server-only changes still appear.

- Signed-in requests, requests with `Authorization` or app cookies, partial
  reloads, stale Inertia versions and development never use the cache. Analytics
  and Cloudflare cookies such as `_ga` and `__cf_bm` don't count as app cookies.
- A response that sets no `Cache-Control` gets `no-store` when it is signed
  in or sets a cookie, such as a sign-in's, and `private, no-cache`
  otherwise: Workers Cache, once enabled, would otherwise keep a page
  rendered per request and serve it to other visitors.
- Browsers always revalidate cached pages. A page is stored only if the final
  response, after all middleware, still allows it: no `Set-Cookie`, and no
  other `Cache-Control`.
- The `X-Popweb-Cache` response header reports `BYPASS` on any request the
  page cache skips, such as a signed-in one, and `HIT`, `MISS` or `DYNAMIC`
  on the pages the default page cache considers; a route with a `{param}`
  placeholder, or with a `cache` option of its own, is not one of them.
- A test of the default page cache stubs the Cache API
  (`Reflect.set(globalThis, 'caches', { default: store })`) and reads each response's body
  before the next request: a page is stored once its body has streamed. A test
  request signed in with `signedIn` sends no session cookie, so it can be
  served a guest's cached page; send the session cookie a browser would.

The framework can't see data a page gets another way, such as an external
`fetch()` or the current time. Give those routes `cache: 'private'`: each
request renders the page, and only the visitor's browser keeps it, checking
back each time (`Cache-Control: private, no-cache`). Give a page only its link
should show, such as a signed preview, `cache: 'no-store'`, which keeps it
out of every cache, the browser's included. `pageCache: false` in `setupWeb`
turns page caching off for the whole application.

A cached page is served before guards and middleware run, so a page a
`guard(...)` decides for is never cached by default, however the guard was
composed before it was provided (`Layer.merge`, `Layer.provide`), nor one
behind `routes.middleware(...)` or under `prefixMiddleware(...)`; with
`setupWeb`'s `middleware` option pages are cached only with
`pageCache: true`. An access check made any other way, such as a layer that
is not a guard or Hono middleware the application adds with `app.use` after
`setupWeb`, that decides from anything the list above does not name, such as
the time or Hono's context, needs `cache: 'private'` on the routes it checks.

## Time-based caching with Workers Cache

To cache pages that do read data for a fixed time, set the route's `cache`
option and enable Workers Cache (`"cache": { "enabled": true }` in Wrangler
config). The option emits Workers Cache headers and tags. It does not publicly
cache authenticated, partial, failed, or mutating responses, nor one whose
producing read a request header, a cookie or request state, such as an API key
a route's own layer or middleware reads before calling `next()`, a country
`setupWeb`'s `middleware` checks, a tenant its `database` factory picks the
database by, or a language the `render` template localizes from: none of
them is part of the cache's key. A header the `database` factory reads keeps
every response of the request out of shared caches, since any of them may
use the database. That key
is the path and query string, not the host, so a Worker serving several
hostnames shares one cache across them: a page that differs by hostname does
not set `cache`. A response that sets a cookie, itself or through
`cookie(...)`, `flash`, `betterAuthCall` or the session lookup, is
`no-store`, and a stricter `Cache-Control` an action adds with
`responseHeader` wins over the option's.

```ts
routes.get(paths.pricing, showPricing, {
  name: 'pricing.show',
  cache: { maxAge: 300, staleWhileRevalidate: 3600 },
})
```

Pages, meaning HTML documents and Inertia page objects, belong to the deploy
that rendered them: the HTML names that build's hashed assets. For pages the
option sends `Cache-Control: public, max-age=0, must-revalidate`, so browsers
revalidate every visit, and puts `maxAge` and `staleWhileRevalidate` in
`Cloudflare-CDN-Cache-Control`, which only Cloudflare reads. Every cached page
carries the `PAGE_CACHE_TAG` Cache-Tag (`popweb:page`). Workers Cache keys
entries by Worker version, so each deploy starts from an empty cache. If you
enable `cross_version_cache`, purge the tag after each deploy:

```ts
const cache = yield* ResponseCacheService
yield* cache.purge({ tags: [PAGE_CACHE_TAG] })
```

Other cached responses, such as JSON APIs and text, use `maxAge` and
`staleWhileRevalidate` in `Cache-Control` for every cache.

Workers Cache answers a hit before the Worker runs, so cached responses vary
on `X-Inertia` and `Cookie`. Workers Cache keeps one entry per value of each,
compared exactly as sent: visitors without cookies share the cached copy, and
a request with cookies is served only an entry stored for the identical
`Cookie` header, never the cookieless copy. A signed-in member sees their own
`auth.user`, a form that redirects back keeps its flashed errors, and neither
response is stored. Visitors carrying only analytics cookies miss the shared
copy, so the option pays off for traffic that arrives without cookies, such as
first visits and crawlers.

That separation is the cache's: it holds only behind a cache that keys on
`Vary`, as Workers Cache does for every header named. Cloudflare's zone cache
ignores `Vary` unless a Cache Rule turns it on, so do not put a zone cache or
another CDN that ignores `Vary` in front of the Worker for these routes: it
would hand the HTML document and the Inertia page object to each other's
visitors.

A bound route's cached page carries the Cache-Tag of each record it reads,
`recordCacheTag(table, primaryKey)` such as `projects:project-1`, whichever
column the route looks the record up by. Tags name tables by their key in the
schema, `planPrices` rather than the SQL name `plan_prices`, and the route
options, `purgeCache` and `cache` take only those and record tags, so a
misspelled table is a type error. `purges` removes cached entries after
a successful write. `purges: true` purges the records the route's bindings name
and the table of its last binding, so a write by id purges the page read by
slug, and the table's tag purges an index that declares it. A cached page
binds its record for anyone, `publicWhen` or `public: true`: registering
`cache` on a route whose record depends on the visitor, an `ownedBy` or
`guarded` binding or one under them, fails, since a shared cache would hand
one visitor's record to the next. Tags name the table, so a write through
the owner's `{project}` purges the public `{showcase}` page of the same row:

```ts
routes
  .get(paths.explore, showPricing, { cache: { maxAge: 300, tags: ['projects'] } })
  .get(paths.projectBySlug, showProjectBySlug, { cache: { maxAge: 300 } })
  .put(paths.project, updateProject, { purges: true })
```

A list of one parent's records, such as a workspace's templates, tags itself
with the child table and the parent, `` `templates:workspace-${workspace.id}` ``,
and the routes that write templates purge that tag with `purgeCache`. Tagging
it with the parent's record instead purges it on every write under the
parent, and with the table on every write to any parent's templates.

`purges: true` names only the route's own records, which for a route that
creates a record under its parent, such as `POST /threads/{thread}/posts`,
are the parent and its table (`threads`), not the new post's. When an action
creates or changes another record, such as a reply's post or the listing an
accepted offer sold, it adds that record's tag with `purgeCache`. The route purges it after the action
succeeds, or leaves with `redirectNow`, together with its own `purges` if it
has any, and not at all when the action fails:

```ts
yield* purgeCache(recordCacheTag('projects', 'project-1'), 'projects')
```

A cached page that reads records beyond its route's bindings, such as the
translation a fallback shows, adds their tags to its response with
`tagCache` in its action, so writes that purge them refresh it; work that
calls it after the response is stored, such as `background()`'s, fails:

```ts
yield* tagCache(recordCacheTag('projects', 'project-1'))
```

`purgeCache` works the same in an Effect run by `routes.run`, such as a
queue consumer that changes a record: the purge runs once the Effect succeeds,
and a purge that fails fails the run, so the queue retries the message and a
scheduled run is recorded as failed. The job runs again on a retry, so it
must be safe to repeat.
Work given to `background()`, or to `ExecutionContextService`'s
`runInBackground` or `schedule`, purges what it names once it succeeds,
whether it runs after the response, as in a Worker, or before it, as in
tests.

## Other patterns

- **Public pages that read data**: the `cache` route option, with
  `purges: true` on the routes that change their records, `purgeCache(...)`
  for other records an action changes, and the table's key in the schema in
  an index page's `tags`. Signed-in visitors render their own page, so the
  same route serves both.

---

<!-- docs/pages.md -->

# Pages and props

## Describe the pages

Each page component's props are an Effect Schema:

```ts
// src/pages.ts
import { Schema as S, Struct } from 'effect'
import { tableSchema } from '@popcomputer/web/schema'
import * as schema from './schema'

// Each page names the columns it shows; the table declares their types.
export const Project = tableSchema(schema.projects).mapFields(
  Struct.pick(['id', 'name', 'userId', 'createdAt'])
)

export const ProjectSummary = tableSchema(schema.projects).mapFields(Struct.pick(['id', 'name']))

export const Task = tableSchema(schema.tasks)

// A page that shows computed values beside columns adds them as fields.
export const ProjectCard = tableSchema(schema.projects).mapFields((fields) => ({
  ...Struct.pick(fields, ['id', 'name']),
  openTasks: S.Number,
}))

// The row a list page ends with, from which the next page continues.
export const ProjectCursor = S.Struct({ beforeAt: S.Date, beforeId: S.String })

export const pages = {
  'Projects/Index': S.Struct({ projects: S.Array(ProjectSummary), next: S.NullOr(ProjectCursor) }),
  'Projects/Show': S.Struct({ project: Project }),
  'Auth/Login': S.Struct({}),
  'Auth/VerifyEmail': S.Struct({ token: S.String }),
  Dashboard: S.Struct({}),
}
```

`render('Projects/Show', props)` accepts only a registered page and props
matching its schema, and encodes the props as JSON through it, so `createdAt`
reaches the browser as an ISO string. A page answers 200, or the status its
third argument gives: `render('Projects/Missing', {}, { status: 404 })`. An
application without `pages` passes props of any declared shape, interfaces
included, whose values JSON carries.

Inertia keeps each page's props in the tab's history, and Back shows them
again without asking the server. A page rendered to a signed-in request, the
session's user or one a layer the route provides gives as `AuthUserService`,
is encrypted there and answered `no-store`. Every page rendered to a visitor
who is not signed in clears the history, as does the first page after a
session ends or another starts, so the next person at the browser cannot
page back through the previous user's pages ([Signing in and
out](sign-in.md)). A signed-in page's version also names its user, and
Inertia asks the server for a page in a tab's history whose version is not
the current page's. Clearing also empties Inertia's prefetch cache. `setupWeb`'s
`history: { encrypt: true }` encrypts every page and `false` none;
`render('Account/Codes', props, { encryptHistory: true, clearHistory: true })`
decides for one page. Inertia encrypts only over HTTPS or on localhost, and
elsewhere warns and keeps the page as it is.

The React component takes its props from the same schema:

```tsx
// src/pages/Projects/Show.tsx
import type { WebPage } from '@popcomputer/web/react'

const Show: WebPage<'Projects/Show'> = ({ project, auth, errors }) => (
  <main>
    <h1>{project.name}</h1>
    <p>Created {new Date(project.createdAt).toLocaleDateString()}</p>
    {auth.user && <p>Signed in as {auth.user.name}</p>}
    {errors.name && <p role="alert">{errors.name}</p>}
  </main>
)

export default Show
```

The client resolves each page by name. A map of every page to its component,
typed `{ readonly [Name in PageName]: WebPage<Name> }` (`PageName` from
`@popcomputer/web/effect`), makes a page without a component a type error. The
resolver checks a name with a guard, `(name): name is PageName => name in
components`, and falls back to the error page, which is not a registered page:
`createInertiaApp({ resolve: (name) => (isPage(name) ? components[name] :
ErrorPage) })`. A page component typed `WebPage<'Name'>` is a React function
component; type the error page `WebErrorPage` from `@popcomputer/web/react`.

A component a page renders takes its props from the same declaration:
`PagePropsFor<'Projects/Show'>['project']` from `@popcomputer/web/react` is the
`project` prop as the browser receives it.

A renamed prop, a missing page or a `Date` used as a `Date` in the browser is a
type error on the side that drifted.

A row joined from several tables spreads `columnsOf` for each table, which
takes the fields that table has: `{ ...columnsOf(stockLevels, StockLine),
...columnsOf(products, StockLine) }`. A field both tables have, such as `id`,
comes from the later one, so leave it out of the other table's:
`columnsOf(products, MovementRow.mapFields(Struct.omit(['id'])))`.

A query reads exactly the columns a page shows with `columnsOf`, which takes
them from the page's schema, beside any values it computes:

```ts
import { count, eq } from 'drizzle-orm'
import { columnsOf } from '@popcomputer/web/schema'
import { ProjectCard } from '../pages'
import { tasks } from '../schema'

const projectCards = dbQuery((db) =>
  db.select({ ...columnsOf(projects, ProjectCard), openTasks: count(tasks.id) })
    .from(projects)
    .leftJoin(tasks, eq(tasks.projectId, projects.id))
    .groupBy(projects.id)
)
```

## Props every page shows

Props every page shows, such as a header's unread count, are declared in
`setupWeb`'s `shared` and computed by `shareProps`, provided on the routes
whose pages show them. It runs when a page renders, never for a redirect or a
JSON response, and returns any of the declared props; an action can also set
one with `share(key, value)`. When it fails, such as when the database is
unavailable, the failure is reported to `EffectErrorObserverService` and the
page renders without those props, which pages treat as optional.

```ts
const sharedRoutes = routes.provide(shareProps(Effect.gen(function* () {
  const viewer = yield* currentUser

  return viewer ? { unreadCount: yield* Effect.succeed(3) } : {}
})))
```

Shared props, such as the unread count `shareProps` computes, arrive on every
page beside its own props. A route that does not provide them leaves them
out, so a page reads them as optional:

```tsx
// src/pages/Dashboard.tsx
import type { WebPage } from '@popcomputer/web/react'

const Dashboard: WebPage<'Dashboard'> = ({ auth, unreadCount }) => (
  <main>
    <h1>{auth.user ? `Welcome back, ${auth.user.name}` : 'Welcome'}</h1>
    {unreadCount !== undefined && <p>{unreadCount} unread</p>}
  </main>
)

export default Dashboard
```

## The error page

The error page is setupWeb's `errors.component`. The boundary renders it for
every failure a page visit ends with, a 404, a 403 or a 500, with the
failure's status, title and message; in development it adds a hint:

```tsx
// src/pages/Error.tsx
import type { WebErrorPage } from '@popcomputer/web/react'
import { paths } from '../paths'

const ErrorPage: WebErrorPage = ({ status, title, message, hint, auth }) => (
  <main>
    <h1>{status}: {title}</h1>
    <p>{message}</p>
    {hint && <pre>{hint}</pre>}
    <a href={auth.user ? paths.dashboard : paths.login}>{auth.user ? 'Back to your dashboard' : 'Sign in'}</a>
  </main>
)

export default ErrorPage
```

The error page is rendered by the boundary, after the action, so it receives
`auth.user` and flash values but not the props `shareProps` computes; give
its layout defaults for them. A value a guard layer `share()`s before the
action does reach it, so a banner every page must show, such as "viewing as
Ada", is shared there.

## The page map

The client maps every registered page to its component. The map's type makes
a page without a component a type error, and the error page, which is not a
registered page, answers any other name:

```tsx
// src/main.tsx
import { createInertiaApp } from '@inertiajs/react'
import type { PageName } from '@popcomputer/web/effect'
import type { WebPage } from '@popcomputer/web/react'
import Login from './pages/Auth/Login'
import VerifyEmail from './pages/Auth/VerifyEmail'
import Dashboard from './pages/Dashboard'
import ErrorPage from './pages/Error'
import ProjectsIndex from './pages/Projects/Index'
import ProjectsShow from './pages/Projects/Show'

const components: { readonly [Name in PageName]: WebPage<Name> } = {
  'Projects/Index': ProjectsIndex,
  'Projects/Show': ProjectsShow,
  'Auth/Login': Login,
  'Auth/VerifyEmail': VerifyEmail,
  Dashboard,
}

const isPage = (name: string): name is PageName => name in components

void createInertiaApp({
  resolve: (name) => (isPage(name) ? components[name] : ErrorPage),
})
```

`createTemplate`'s `scripts` loads this module, built by Vite or another
bundler; `createVersion(manifest)` changes with every build, so a visitor on
an old build reloads into the new one.

## Other patterns

- **Counts in the header**, such as unread messages: declare them in
  `shared` and compute them with `shareProps`, which runs only when a page
  renders.

---

<!-- docs/responses.md -->

# Cookies, files and headers

## Cookies

An application cookie, such as a guest's cart, is declared once with the
schema of its value, and actions read, set and clear it through the
declaration. The response carries what they set, beside flash, so a set
cookie survives the redirect after a form:

```ts
import { Option } from 'effect'
import { cookie } from '@popcomputer/web/effect'

export const cartCookie = cookie('cart', S.Struct({ id: S.String }), { maxAge: '30 days', path: '/r' })

export const addToCart = action(Effect.gen(function* () {
  const cart = Option.getOrElse(yield* cartCookie.read, () => ({ id: crypto.randomUUID() }))

  yield* cartCookie.set(cart)

  return yield* redirect(paths.dashboard)
}))
```

A value the browser sends that the schema rejects reads as none, and setting
one the schema rejects is a defect naming the cookie, so check limits first.
A value whose JSON form is a string, such as a token, is stored as it is, so a
cookie written by hand before reads the same.

Reading a cookie renders the page afresh for each request, and a cached page
whose path a cookie covers is rendered afresh for every visitor carrying it,
so scope a cookie to the paths that read it: `path: '/r/{restaurant}/'` takes
its placeholder from the route that sets it, and covers `/r/acme/cart` but
not the menu at `/r/acme`.

Cookies are `HttpOnly`, `SameSite=Lax`, and `Secure` over HTTPS. An unsigned
cookie holds whatever a visitor sends, so it suits a preference or a pointer
the server checks. One the server must trust is declared with
`signed: { secret: 'COOKIE_SECRET' }`, naming the binding that holds the
secret, and a value without a valid signature reads as none. A secret the
bindings lack fails when the cookie is first read or set, so set a signed
cookie before the writes it goes with.

`betterAuthLogoutAction({ clear: [impersonationCookie] })` clears such
cookies on sign-out. A cookie set before the action fails is still sent with
the failure's response. A test reads the value a response set with
`readCookie(res, cartCookie)` from `@popcomputer/web/testing`.

## Files, headers and polling

`file(body, { contentType, filename })` answers with a file, such as an export
or a feed: text, bytes, or an Effect `Stream` sent as it is produced. A
`filename` offers it as a download. [Serving an upload back](#serving-an-upload-back)
shows doing so safely.

`json` and `text` take `{ status, headers }` as well as a status, and an
`etag` naming the version of what they hold, such as a counter the writes
bump: a client polling with `If-None-Match` gets `304 Not Modified` with no
body until it changes,
``json(KitchenOrders, orders, { etag: `orders-${version}` })``. When building
the body costs a query, `ifChanged(etag, response)` answers the 304 before
running the response's Effect at all.

A guard layer adds a header to every response of its routes, failures
included, with `responseHeader('Deprecation', 'true')`, as for an API's
rate-limit headers. An `HttpError` adds its own `headers` to the response, as
`HttpError.rateLimited(30)` adds `Retry-After`. `routes.options(path, action)`
answers a CORS preflight, with `noContent(headers)` for its 204.

## Serving an upload back

Serve an upload back with `file(bytes, { contentType, filename })`: the
`filename` makes it a download, and `file` always sends
`X-Content-Type-Options: nosniff`, so the browser keeps to the declared type.
It serves only an image other than SVG, a PDF, plain text, JSON, audio or
video as it is: any other body, such as HTML, SVG or XML, gets
`Content-Security-Policy: sandbox`, a download too, since a web view may show
an attachment in place of saving it, unless the response's `headers` set
their own policy. A `contentType` that is not one media
type, such as `image/png;x=,text/html`, which a browser reads by its last
type, is sent as `application/octet-stream`; `upload()` refuses such a file,
and keeps only its media type, so store `file.type` as it decodes. Name the
stored object with a key the server makes, never the upload's file name, and
check who may read the file before serving it, as for any record.

## Requests from other sites, and security headers

`setupWeb` refuses a state-changing request whose `Origin` (or `Referer`)
names another site with 403, through the error boundary, so a visit gets the
error page and a JSON client the envelope, beside the `SameSite` cookies
Better Auth sets. A request without either header, such as a webhook, passes,
and so does one whose `Authorization` header holds a token, such as
`Bearer`, which a browser never adds by itself. `Basic`, `Digest`,
`Negotiate` and `NTLM` credentials are checked like a cookie, since a browser
resends the ones it cached, as behind a staging gate, with another site's
form. A native app or another site that posts to the application is listed
in `security: { verifyOrigin: { allowedOrigins: ['https://admin.example'] } }`.

Every response also gets, unless it sets its own, `X-Content-Type-Options:
nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, which keeps the
same-site `Referer` a failed form goes back to (Hono's `secureHeaders()`
defaults to `no-referrer`, which sends every failed form to `/`), and framing
refused, `X-Frame-Options: DENY` with `frame-ancestors 'none'` added to its
`Content-Security-Policy`, so another site cannot frame a page under a decoy
to trick a visitor into clicking. `security: { headers: { frames:
'same-origin' } }` lets the application frame its own pages, and `headers:
false` sends none of them.

---

<!-- docs/route-models.md -->

# Route model binding

Name each model's Drizzle table once, in `setupWeb`'s `bindings`, with who may
load its record, then use Laravel-style route placeholders:

```ts
import * as schema from '../schema'

const bindings = {
  project: routeBinding(schema.projects, { ownedBy: 'userId' }),
  task: routeBinding(schema.tasks, { scope: { project: { foreignKey: 'projectId' } } }),
}

routes
  .get(paths.project, showProject)
  .get(paths.projectBySlug, showProjectBySlug)
  .get(paths.task, showTask)
```

Inside `showTask`, both models from the nested route are available by name:

```ts
const project = yield* bound('project')
const task = yield* bound('task')
```

## Who may load a record

Laravel's route model binding finds a record and leaves who may see it to a
policy each action has to remember to call. Here the binding says it, once,
beside its table, and the lookup's query enforces it, so no action has to
remember the check:

| Option | Who loads the record | Anyone else |
| --- | --- | --- |
| `ownedBy: 'userId'` | The signed-in user whose id the column holds, a column that references the users table's `id` | The 404 a missing record gets. A signed-out visitor is asked to sign in, before the database is asked |
| `publicWhen: { isPublic: true }` | Anyone, when its columns hold these values, each typed by its column, as `{ visibility: 'public' }` | 404, its owner included |
| `public: true` | Anyone, signed in or not | Nobody else |
| `guarded: true` | Anyone the route's guard lets through, as a membership guard lets in an organization's members. The record loads only once a `guard(...)` the route is provided has read it and let the visitor in: asked for first by an action, another layer or a guard that reads a record under it, it fails | The guard's answer: 404 for a stranger, as [Guards and roles](guards.md#roles-belong-to-memberships-read-by-a-guard) shows |

A record that lives inside another, such as a book in a list, says `scope`
instead: `book: routeBinding(schema.books, { scope: { list: { foreignKey: 'listId' } } })`
loads a book only under its list, so the list's option decides. Registering
a route that names `{book}` without `{list}` fails, and so does a child that
says `public: true` under a parent that says who may load it, since it would
load for anyone on a path without the parent.

A binding gives one option: two fail when `setupWeb` is called
(`WEB_RTE_606_BINDING_ACCESS_INVALID`), as do a column the table lacks, an
option whose value says nothing, such as `ownedBy`, `guarded` or `scope`
read from an absent setting or `public: false`, and a `publicWhen` value
that is undefined, which a SQLite boolean column would read as false. The
`require-binding-access` [lint rule](lint-rules.md) reports a binding that
gives none, which loads any record its path names, for anyone.

The signed-in user is the session's, or the one a layer the route provides
gives, as an API key's does. An `ownedBy` column declares that it holds a
user's id,
`userId: text('user_id').notNull().references(() => user.id)`, naming the
table `betterAuthSession` was given, or else Better Auth's `user`. One that
references another table, or no table, fails when `setupWeb` is called
(`WEB_RTE_607_BINDING_OWNER_NOT_USER`): compared with the signed-in user's
id, it would match no record.

A record an organization owns loads under the organization, as
`/orgs/{organization:slug}/projects/{project}`: the organization's binding is
`guarded: true`, with the membership guard that decides provided to its
routes, and the project is scoped to it,
`scope: { organization: { foreignKey: 'organizationId' } }`. A member loads
the organization's projects, anyone else gets the guard's 404, and another
organization's project under this one's path is a 404 too. A record that
belongs to a user through a parent, such as a book in a list, loads under
the parent the same way, the list `ownedBy: 'userId'`, unless it holds a
`userId` of its own.

One table can be bound twice, for two kinds of page. A project's own pages
bind `{project}` for its owner, and the page anyone may see binds
`{showcase}` from the same table, under a path of its own, such as
`/showcase/{showcase}`:

```ts
import * as schema from '../schema'

const bindings = {
  project: routeBinding(schema.projects, { ownedBy: 'userId' }),
  showcase: routeBinding(schema.projects, { publicWhen: { isPublic: true } }),
}
```

## What a model is

`bound('task')` is the table's row, checked against the table's columns as it
loads: their types, nullability and enum values. A parameter name need not
match its table: `bindings: { author: schema.users }` loads `{author}` from
`users`. A JSON column, or a text column narrowed with `$type<Role>()`, is
typed but not checked by its column: name an Effect Schema for the binding,
such as `tableSchema(schema.contacts, { custom: CustomValues })`, whose
overrides check those columns and derive the rest; the binding loads from the
table the schema was built from.

## When a model loads

A route loads its models the first time the action calls `bound()`, so a
guard or `authorize()` that runs first decides before any database lookup,
and a signed-out visitor cannot tell an existing record from a missing one.
A missing row fails `bound()` with `NotFoundError`, which renders a 404. The
route's models load together, so a missing one is a 404 whichever the action
asks for. A guard's read loads only the record it reads and those before it
in the path, and the rest load on the first read after the guards, so a
visitor a guard turns away learns nothing of the records under the one it
decides for, even when it answers 403 or redirects. A guard that reads a
record under a `guarded` one fails until that one's guard has decided.

`{post}` looks the record up by the table's `id` column, or, for a table
without one, its primary key. `{post:slug}` names the column by its property
key in the table (`certificateToken`, not the SQL `certificate_token`), and a
column the table lacks fails when the route is registered.

To lock a bound record inside `dbTransaction`, read it again by its id with
`.for('update')`, as [Rules live in services](services.md#rules-live-in-services-actions-decide-what-a-failure-means)
shows; the bound row was read before the transaction began.

## Nested models are scoped to their parent

A nested binding is scoped to the binding before it. Drizzle's metadata
finds the relationship when the child's column references the parent's
(`.references(() => projects.id)`) or a relation declares it, so `{task}`
under `{project}` loads only the project's tasks: another project's task
under this one's path is a 404. Name the relationship with `scope`, which
also says the binding loads only under its parent, so the parent's option
decides who may load it. `scope` can name an earlier binding than the one
before it, such as a project's flag under one of the project's environments,
`/projects/{project}/environments/{environment}/flags/{flag:key}`. `setupWeb`
checks each scope's binding and columns when it is called:

```ts
import * as schema from '../schema'

const routeBindings = {
  task: routeBinding(schema.tasks, {
    scope: {
      project: { foreignKey: 'projectId' },
    },
  }),
}
```

This fails closed when a child lookup cannot be safely scoped to its parent.

A membership is a route model like any other: with
`member: routeBinding(schema.memberships, { scope: { organization: { foreignKey: 'organizationId' } } })`
among the bindings, `/orgs/{organization:slug}/members/{member:userId}` loads
the organization's membership of the user the path names, by its `userId`
column, and another organization's member is a 404. Bind every record a path
names this way, rather than reading its id as a plain parameter and querying
for it.

## A lookup names one record

A lookup column must name one record within the route's scope: a slug unique
only within an organization belongs under it, as
`/orgs/{organization:slug}/events/{event:slug}`. When the column matches more
than one row, `bound()` fails (`WEB_RTE_605_BINDING_AMBIGUOUS`) instead of
picking one. An `ownedBy` binding's lookup is scoped by its owner, so a
slug unique to each user names one record. Any other tenant the route takes
from the signed-in user rather than its path, such as a member's company,
does not scope a lookup: put the tenant in the path
(`/c/{company:slug}/shops/{shop:code}`), which also keeps links to another
tenant's records from loading, or make the column unique across tenants.

## Plain parameters

A placeholder without a binding is a plain parameter: the action reads it
with `validateRequest`, beside the route's models. In
`/teams/{team}/invites/{token}`, `bound('team')` loads the team and `token`
arrives with the request's input, to be looked up like any other input,
scoped by the team. A page that answers when a record is missing, such as an
article that falls back to another locale, takes that parameter as a plain
parameter too, queries with it scoped by its bound parent, and tags its
cached response with what it read using `tagCache`.

## Reading a model outside the action

`bound('project')` needs a route whose path, or prefix, has `{project}`: the
types track it as the Effect requirement `RouteModel<'project'>`, which only
such a route provides. An action, or a guard layer, that reads a model its
route does not bind fails to type-check where the route is registered, with
`missingRouteModels: "project"`. A helper that reads a model states the
requirement in its type, `BoundRequirements<'project'>`, so every action that
uses it carries it:

```ts
import type { BoundModelError, BoundRequirements } from '@popcomputer/web/effect'

type Project = typeof projects.$inferSelect

// The route's project, or a 403 once it is archived.
export const openProject: Effect.Effect<Project, BoundModelError | ForbiddenError, BoundRequirements<'project'>> =
  Effect.gen(function* () {
    const project = yield* bound('project')

    if (project.archivedAt !== null) return yield* forbidden('This project is archived.')

    return project
  })
```

An action calls it, `const project = yield* openProject`, and only a route
with `{project}` accepts that action.

A test that runs such a helper outside a route provides
`BoundModels.fromModels({ project })`, which binds the models it holds.

Route model binding is currently Drizzle-specific even though the basic
`DatabaseService` can hold any application database client.

---

<!-- docs/services.md -->

# Application services

Services an action needs beyond the framework's are Effect layers, given
with `web.services(...)` once `web` is registered. It returns the routes,
which accept actions that use them.

```ts
// src/services.ts
import { Config, Context, DateTime, Effect, Layer } from 'effect'
import { config } from '@popcomputer/web/effect'

export class Clock extends Context.Service<Clock, {
  readonly today: Effect.Effect<string>
  readonly timeZone: string
}>()('app/Clock') {}

// config reads the Worker's bindings, named as src/env.ts declares them:
// here the TIME_ZONE var.
export const ClockLive = Layer.effect(Clock, Effect.gen(function* () {
  const timeZone = yield* config.string('TIME_ZONE').pipe(Config.withDefault('UTC'))
  // An unknown zone is a deployment mistake: the layer fails to build, naming it.
  const zone = yield* DateTime.zoneMakeNamedEffect(timeZone).pipe(Effect.orDie)

  return Clock.of({
    // DateTime.now reads Effect's Clock, so testClock moves today as well.
    today: Effect.map(DateTime.now, (now) => DateTime.formatIsoDate(DateTime.setZone(now, zone))),
    timeZone,
  })
}))

export class AuditLog extends Context.Service<AuditLog, {
  readonly record: (event: string) => Effect.Effect<void>
}>()('app/AuditLog') {}

export const auditLogFor = (kv: KVNamespace) => Layer.succeed(AuditLog, AuditLog.of({
  record: (event) => Effect.promise(() => kv.put(`audit:${event}`, event)),
}))
```

In `src/app.ts`, after the `Register` declaration, the routes come from
`web.services(...)` in place of `export const { app, routes } = web`:

```ts
export const { app, routes } = web.services({
  app: ClockLive,
  request: (c) => auditLogFor(c.env.KV),
})
```

The `app` layer is built once, on the first request an isolate serves, and
shared by every later request: configuration, clients that open no connection
until used, in-memory caches. `config` from `@popcomputer/web/effect` is
Effect `Config` named by the bindings `src/env.ts` declares, so a misspelled
name is a type error: it reads the Worker's bindings in both kinds of service
and in actions, and `config.redacted('PAYMENT_WEBHOOK_SECRET')` reads a
secret. A missing binding fails the request with a configuration error that
names it in development. The `request` layer is built for each request from
its context and bindings, when the request runs an action: a plain Hono
route never calls `request(c)`. Anything holding a request's I/O, such as a D1, KV or
Hyperdrive binding, belongs in `request`: Workers forbid using it from
another request. A request service built from a request header, `c.req.raw`
or `c.req.url`, such as a tenant named by `X-Tenant`, makes every page that
runs it render per request, as reading a header does in an action, since no
cache key holds them. A request service replaces an application service with the
same tag. For services only some routes need, use `routes.provide(layer)`.

A layer's type is inferred, even when it reads the database, `config` or
`bound`: `web.services` comes after the registration, so the types those read
do not depend on the layer. A service that queries the database keeps
`DatabaseService` in its methods' requirements rather than providing it
itself, so a method called inside `dbTransaction` takes part in the
transaction:

```ts
import { eq } from 'drizzle-orm'

type Project = typeof projects.$inferSelect

export class Projects extends Context.Service<Projects, {
  readonly ownedBy: (
    userId: string
  ) => Effect.Effect<ReadonlyArray<Project>, DatabaseError, DatabaseService>
}>()('app/Projects') {}

export const ProjectsLive = Layer.succeed(Projects, Projects.of({
  ownedBy: (userId) =>
    dbQuery((db) => db.select().from(projects).where(eq(projects.userId, userId))),
}))
```

## Rules live in services; actions decide what a failure means

Put a business rule in an Effect service whose methods fail with
`Schema.TaggedError` errors, and let the action turn each failure into a
response with `Effect.catchTags`: `invalid(...)` for an error that belongs
beside a form field, `notFound(...)` or `forbidden(...)` for access, and
`flash(...)` then `back(...)` for a refusal the visitor should read. A failure
the action leaves unhandled is a type error at its registration, naming it in
`unhandledErrors`.

The transaction can live in the service, as below, or in the action that
calls several services' methods inside one `dbTransaction`; either way, a
typed failure after a write, such as a rule a later step checks, rolls that
write back.

A limit checked by counting and then inserting lets two concurrent requests
both pass the count. Inside `dbTransaction`, lock the row the limit belongs to
first (`for('update')` on Postgres), so the second request counts after the
first one writes.

```ts
import { count, eq } from 'drizzle-orm'
import type { DatabaseWriteError } from '@popcomputer/web/effect'
import { requiredString } from '@popcomputer/web/schema'
import { tasks } from '../schema'

export class TaskLimitReached extends S.TaggedError<TaskLimitReached>()('TaskLimitReached', {
  limit: S.Number,
}) {}

export class Tasks extends Context.Service<Tasks, {
  readonly add: (
    projectId: string,
    title: string
  ) => Effect.Effect<void, TaskLimitReached | DatabaseWriteError, DatabaseService>
}>()('app/Tasks') {}

export const TasksLive: Layer.Layer<Tasks> = Layer.succeed(Tasks, Tasks.of({
  add: (projectId, title) =>
    dbTransaction(Effect.gen(function* () {
      yield* dbQuery((db) => db.select().from(projects).where(eq(projects.id, projectId)).for('update'))
      const [row] = yield* dbQuery((db) =>
        db.select({ tasks: count() }).from(tasks).where(eq(tasks.projectId, projectId))
      )

      if ((row?.tasks ?? 0) >= 100) return yield* new TaskLimitReached({ limit: 100 })

      yield* dbMutation((db) => db.insert(tasks).values({ id: crypto.randomUUID(), projectId, title }))
    })),
}))

export const addTask = action(Effect.gen(function* () {
  // Its owner's only: the binding is ownedBy 'userId'.
  const project = yield* bound('project')
  const input = yield* validateRequest(S.Struct({ title: requiredString }))
  const service = yield* Tasks

  return yield* service.add(project.id, input.title).pipe(
    Effect.andThen(redirect(paths.project, { project: project.id })),
    Effect.catchTags({
      TaskLimitReached: (error) => invalid({ title: `A project holds at most ${error.limit} tasks.` }),
    })
  )
}))
```

## Other patterns

- **State machines**: model a record's states as a `Schema.TaggedUnion`
  (build a state with `.cases.Draft.make(...)`) and its transitions as one
  function returning an Effect that fails with a typed error for an illegal
  one; the action maps those errors, all of them with one handler when they
  answer alike (`Effect.catchTag(['ClaimLocked', 'AlreadyPaid'], refuse)`),
  and a page schema built from the union lets React switch over the states
  exhaustively.
- **Services that join transactions**: keep `DatabaseService` in a service
  method's requirements (`Effect.Effect<A, E, DatabaseService>`) instead of
  providing it inside the service, so a method called in `dbTransaction`
  takes part in it.

---

<!-- docs/setup.md -->

# Quick start

Every type an application uses is declared once, as a value, and the rest of
the application is typed by it: the database client, the Better Auth client,
the signed-in user, route models, pages, shared props and flash data.

## 1. Describe the Worker's bindings

```ts
// src/env.ts
import { Schema as S } from 'effect'
import { defineEnv, randomSecret, secret, variable, type EnvBindings } from '@popcomputer/web/env'

export const env = defineEnv({
  DATABASE_URL: secret(),
  BETTER_AUTH_SECRET: secret(S.String.check(S.isMinLength(32)), { generate: randomSecret }),
  PAYMENT_WEBHOOK_SECRET: secret(S.String.check(S.isStartingWith('whsec_'))),
  APP_URL: variable(S.String),
  TIME_ZONE: variable(S.String, { optional: true }),
})

export type Bindings = EnvBindings<typeof env> & { KV: KVNamespace; SIGN_IN_LIMITER: RateLimit }

export type Env = { Bindings: Bindings }
```

The vars and secrets are declared once, and checked before an isolate
serves: [Vars and secrets](env.md) shows how. `APP_URL`, such as
`https://app.example.com`, is Better Auth's `baseURL`, the origin its emailed
reset, verification and magic links name: read from each request's URL
instead, they would follow whatever host and scheme reached the Worker.

## 2. Describe the pages

Each page's props are an Effect Schema in `src/pages.ts`, and each React
page takes its props from it: [Pages and props](pages.md) shows both.

## 3. Configure the application once, and register it

```ts
// src/app.ts
import { Hono } from 'hono'
import { Schema as S, Struct } from 'effect'
import { createTemplate, createVersion, setupWeb } from '@popcomputer/web'
import { betterAuthSession } from '@popcomputer/web/auth'
import { routeBinding } from '@popcomputer/web/effect'
import { tableSchema } from '@popcomputer/web/schema'
import { createAuth } from './auth'
import { createDb } from './db'
import { sendEmail } from './email'
import manifest from '../dist/manifest.json'
import { env, type Env } from './env'
import { pages } from './pages'
import { paths } from './paths'
import * as schema from './schema'

export const web = setupWeb(new Hono<Env>(), {
  version: createVersion(manifest),
  render: createTemplate({
    title: 'Projects',
    scripts: [manifest['src/main.tsx']?.file].filter(Boolean),
    styles: manifest['src/main.tsx']?.css ?? [],
  }),
  database: (c) => createDb(c.env.DATABASE_URL),
  schema,
  bindings: {
    project: routeBinding(schema.projects, { ownedBy: 'userId' }),
    showcase: routeBinding(schema.projects, { publicWhen: { isPublic: true } }),
    task: routeBinding(schema.tasks, { scope: { project: { foreignKey: 'projectId' } } }),
    organization: routeBinding(schema.organizations, { guarded: true }),
    member: routeBinding(schema.memberships, { scope: { organization: { foreignKey: 'organizationId' } } }),
  },
  pages,
  paths,
  auth: {
    client: (c, { db, backgroundTasks }) => createAuth({
      db,
      secret: c.env.BETTER_AUTH_SECRET,
      baseURL: c.env.APP_URL,
      sendEmail: (email) => sendEmail(c.env, email),
      advanced: { backgroundTasks },
    }),
    // The user's fields are the user table's; pages see only `share`'s.
    session: betterAuthSession(tableSchema(schema.user)),
    // Slow password guessing: wrangler.jsonc's limiter, and the table that counts failures.
    signInLimits: { limiter: 'SIGN_IN_LIMITER', table: schema.rateLimit },
    share: tableSchema(schema.user).mapFields(Struct.pick(['id', 'name', 'image'])),
  },
  shared: S.Struct({ unreadCount: S.Number }),
  flash: S.Struct({ success: S.String }),
  errors: { component: 'Error' },
  env,
})

declare module '@popcomputer/web' {
  interface Register {
    web: typeof web
  }
}

export const { app, routes } = web
export default app
```

Registering `setupWeb`'s result is the one declaration the rest of the
application reads its types from:

| Declared in `setupWeb` | Types |
| --- | --- |
| `new Hono<Env>()` | `BindingsService`, Effect `Config`, `testEnv`'s bindings |
| `env` | the vars and secrets in `Bindings`, through `EnvBindings`, checked when an isolate starts |
| `database` | `DatabaseService` and the `db` in `dbQuery`, `dbMutation`, `dbBatch` |
| `schema`, `bindings` | `bound('project')`, its keys, the model's row type and who may load it |
| `auth.client` | `AuthService`, and the endpoints `betterAuthRedirect` and `betterAuthCall` call |
| `auth.session` | `authorize()`, `currentUser`, `AuthUserService`, `signedIn` |
| `auth.share` | `auth.user` in `SharedProps` and `WebPage` (default: `id`, `name`, `image`) |
| `pages` | `render`, `jsonOrRender`, `WebPage`, `readPage` |
| `paths` | the paths `routes.get(...)` and the other registrations accept |
| `shared`, `flash` | `shareProps(effect)`, `share(key, value)`, `flash(key, value)`, `SharedProps`, `FlashData` |

Each value reaches the browser encoded through its schema, so a field the
schema does not name, such as the user's email, never leaves the server.
Inertia's own `usePage()` reads the same types from one more declaration:

```ts
// src/inertia.d.ts
import type { FlashData, SharedProps } from '@popcomputer/web/react'

declare module '@inertiajs/core' {
  interface InertiaConfig {
    sharedPageProps: SharedProps
    flashDataType: FlashData
  }
}
```

The database and Better Auth come from two small factories. On Postgres,
through Hyperdrive in production:

```ts
// src/db.ts
import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core'
import { drizzle } from 'drizzle-orm/postgres-js'
import postgres from 'postgres'
import * as schema from './schema'

// Drizzle's driver-independent Postgres database: a PGlite client in tests
// has this type too, so testEnv accepts it in place of Hyperdrive's.
export type Database = PgDatabase<PgQueryResultHKT, typeof schema>

export function createDb(url: string): Database {
  return drizzle(postgres(url), { schema })
}
```

Better Auth's factory, `src/auth.ts`, and the mailer it sends through, `src/email.ts`, are in
[Auth](auth.md#better-auths-client); the tables it reads and writes, in [Better Auth's tables](auth-tables.md).

On Cloudflare D1, `createDb` takes the binding instead,
`drizzle(c.env.DB, { schema })` from `drizzle-orm/d1`, and the adapter's
`provider` is `'sqlite'`. Type the database as `ReturnType<typeof createDb>` or
Drizzle's `DrizzleD1Database<typeof schema>`: either way `dbTransaction` is a
type error on D1, which has no interactive transactions.

Database-backed auth receives the database as an explicit dependency. The
alternatives below need no placeholders or explicit generics:

```ts
const version = createVersion(manifest)
const template = createTemplate({ title: 'Projects' })

// Public application
setupWeb(app, { version, render: template })

// Database without auth
setupWeb(app, { version, render: template, database: (c) => createDb(c.env.DATABASE_URL) })

// Stateless auth
setupWeb(app, {
  version,
  render: template,
  auth: {
    client: (c, { backgroundTasks }) => createStatelessAuth({
      secret: c.env.BETTER_AUTH_SECRET,
      advanced: { backgroundTasks },
    }),
  },
})
```

`setupWeb` installs the middleware stack and error boundary and returns
`{ app, routes }`; for manual composition, see [Lower-level composition](lower-level.md).

## 4. Write actions and register routes

Each route's path is declared once in `src/paths.ts`, and each action is
registered on `routes`: [Actions and routes](actions.md) shows both.

## 5. Write the client

Forms take their fields from the schema their action validates, as
[Forms](forms.md) shows, and the client maps each page to its component, as
[Pages and props](pages.md#the-page-map) shows.

## 6. Wire the Worker

A route is registered when the module that registers it runs, so the
Worker's entry imports every module of registrations. A module nothing
imports leaves its routes answering 404, with no error to say why. Point
Wrangler's `main` at the entry, `"main": "src/worker.ts"` in
`wrangler.jsonc`:

```ts
// src/worker.ts
import { app } from './app'
import './routes'
import './auth-routes'
import './api-routes'

export default app
```

A Worker that also runs Cron Triggers or a Queue consumer exports their
handlers beside `fetch`, as [Scheduled and queued work](background.md#scheduled-and-queued-work)
shows. A test imports the same modules, or the entry itself, before its first
request.

Each file of the application declares one thing, and the rest reads it:

| File | Declares | Read by |
| --- | --- | --- |
| `src/env.ts` | the Worker's bindings | `new Hono<Env>()`, `config`, `testEnv`'s bindings |
| `src/schema.ts` | the Drizzle tables | `bindings`, `tableSchema`, `columnsOf`, cache tags, Better Auth |
| `src/db.ts`, `src/auth.ts`, `src/email.ts` | the database, Better Auth and mail clients | `setupWeb`'s `database` and `auth.client` |
| `src/paths.ts` | every route's path | `routes`, `redirect`, `back`, `href`, endpoint contracts |
| `src/pages.ts` | each page's props | `render`, `WebPage`, `readPage` |
| `src/forms.ts` | each form's fields | `validateRequest` in actions, `FormInput` in React |
| `src/endpoints.ts` | each JSON endpoint's contract | `action(endpoint, ...)`, `routes.endpoint`, `call`, `openApi` |
| `src/services.ts` | application services and their layers | `web.services(...)` in `src/app.ts` |
| `src/app.ts` | `setupWeb(...)`, its registration, and `web.services(...)` | every type above, and the routes |
| `src/routes.ts` and other route modules | the registrations | `src/worker.ts` |
| `src/actions/**` | one action per route | the route modules |
| `src/pages/**`, `src/main.tsx` | the React pages and the page map | the browser bundle |

The browser bundle may import `src/paths.ts`, `src/forms.ts` and
`src/endpoints.ts`, which import only `effect`, the validators and the paths.
Everything else is server code: a React page reads its props through
`WebPage`, which takes them from the registration, never by importing
`src/pages.ts`, which reads the tables.

---

<!-- docs/sign-in.md -->

# Signing in and out

Sign-in, sign-up and sign-out are ordinary routes on the `routes` setupWeb
returns. `routes.provide(layer)` guards every route registered through it:
`RequireGuestLayer` sends a signed-in member home, and `RequireAuthLayer`
sends a signed-out visitor to `auth.signInPath` (default `/login`), as
`authorize()` does. A sign-in action validates its form like any action, then
calls a Better Auth endpoint, by its name on `auth.api`, through
`betterAuthRedirect`, which answers with a redirect carrying the session
cookie:

```ts
// src/actions/auth.ts
import { Effect } from 'effect'
import { action, intendedUrl, validateRequest } from '@popcomputer/web/effect'
import { betterAuthRedirect } from '@popcomputer/web/auth'
import { SignIn } from '../forms'
import { paths } from '../paths'

export const signIn = action(
  Effect.gen(function* () {
    const input = yield* validateRequest(SignIn)
    const redirectTo = yield* intendedUrl(paths.projects)

    return yield* betterAuthRedirect('signInEmail', { body: input }, {
      redirectTo,
      errors: (error) => ({ email: error.message }),
    })
  })
)
```

The call goes through Better Auth's request handler, as its own client's calls
do, so its rate limits, origin checks and plugins' hooks apply to the form as
they do to its routes; a call to `auth.api` skips them, leaving a sign-in form
open to password guessing. It reaches Better Auth at `baseURL`, and a form's
own origin, such as a Version URL's, moves there with it, so the origin check
passes the application's own pages and judges other sites by `trustedOrigins`.
Better Auth's types name every endpoint, plugins' too, and type each one's body
and result, so a misspelled endpoint or a missing password is a type error. A
sign-in its rate limit refuses fails with `AuthRateLimitError`, which the error
page answers with a 429; show it on the form instead with
`Effect.catchTag('AuthRateLimitError', () => invalid({ email: 'Too many attempts. Try again in a minute.' }))`.
Validate a sign-in's password with `currentPassword`, which keeps it as typed:
`requiredString` trims, so a password chosen with outer spaces would never sign
in. `password({ min: 12 })` checks one a visitor chooses, on signing up.
`RequireGuestLayer` sends a signed-in visitor from a guest page to `setupWeb`'s
`auth.homePath`, `/` by default. In tests, each `testBrowser` is a client at
its own address, so the limits count each browser apart.

```ts
// src/auth-routes.ts
import { action, render, RequireAuthLayer, RequireGuestLayer } from '@popcomputer/web/effect'
import { betterAuthLogoutAction } from '@popcomputer/web/auth'
import { routes } from './app'
import { signIn } from './actions/auth'
import { showDashboard } from './actions/dashboard'
import { paths } from './paths'

routes
  .provide(RequireGuestLayer)
  .get(paths.login, action(render('Auth/Login')))
  .post(paths.login, signIn)

routes.provide(RequireAuthLayer).get(paths.dashboard, showDashboard)

routes.post(paths.logout, betterAuthLogoutAction({ redirectTo: paths.login }))
```

A signed-out visit to a guarded page goes to the sign-in path with the page as
`?redirect=`, and `intendedUrl(fallback)` returns there after signing in; it
returns only paths on this site. A rejection, such as a wrong password or an
address not yet proven, goes back to the form with the field errors `errors` returns; rate limits and Better Auth
failures stay separate typed errors. Sign-up works the same way with
`'signUpEmail'`, after whatever else the action does with the input, and
signs nobody in until the emailed link proves the address, as
[Proving an address](auth.md#proving-an-address) shows.

Signing out expires the session cookie, and the page `betterAuthLogoutAction`
redirects to clears Inertia's history: the signed-in pages, which Inertia kept
there encrypted, cannot be shown again with Back by the next person at the
browser ([Pages and props](pages.md)). Every page rendered to a visitor who is
not signed in clears it, in any tab, however the session ended: in another
tab, by its cookie's expiry, or where a prefetch or a JSON answer saw it end.
For the next member to sign in there, the first page after any answer that
ends the session or starts another clears it, through JSON answers between:
Better Auth's client signing in or out through `betterAuthHandler`, or a
lookup that finds the session revoked. That page reaches one tab; every
signed-in page's version names its member, so Back in any tab whose page
went to the new member asks the server. A session cookie renamed in Better
Auth, not given a `cookiePrefix`, is named in `auth.sessionCookie`.

Better Auth writes the new user itself, so the application's own record of
a member, such as a profile, is a second write. Make it on the member's first
visit, in a guard layer on the routes that need it: a user Better Auth
created from an OAuth provider or a magic link never passes through the
application's sign-up action, and a failure between the two writes leaves
nothing the next visit cannot repair:

```ts
// src/profiles.ts
import { eq } from 'drizzle-orm'
import { Effect, Layer } from 'effect'
import { authorize, dbMutation, dbQuery } from '@popcomputer/web/effect'
import { profiles } from './schema'

// The application's own record of each member, however they signed up.
export const EnsureProfile = Layer.effectDiscard(Effect.gen(function* () {
  const auth = yield* authorize()
  const [existing] = yield* dbQuery((db) => db.select().from(profiles).where(eq(profiles.userId, auth.user.id)).limit(1))

  if (existing === undefined) {
    yield* dbMutation((db) =>
      db.insert(profiles).values({ userId: auth.user.id, displayName: auth.user.name }).onConflictDoNothing()
    )
  }
}))
```

Provide it beside the guard:
`routes.provide(RequireAuthLayer).provide(EnsureProfile).get(paths.dashboard, showDashboard)`.

Fields the server sets rather than the form, such as a role or a team, are
`input: false` in `betterAuthFields`, so a sign-up cannot send them: keep
them in the application's own table, such as a membership, which a guard
layer reads. `redirectTo` given a function receives the endpoint's result,
sign-in's `{ token, user }`, so it reads the user's id as
`result.user.id`; sign-up's names a made-up user when the address is already
registered, so key nothing on it. A result is the JSON Better Auth's handler answered, and
typed so: its dates are ISO strings.

A Better Auth call whose result the action uses, such as enabling two-factor
(which returns the secret) or checking a password, goes through
`betterAuthCall('enableTwoFactor', { body }, { errors })` from
`@popcomputer/web/auth`, which sends it as `betterAuthRedirect` does, maps its
failures the same way and returns the result. A link
Better Auth emails, such as a reset link, points at its own `/api/auth/*`
endpoint; build the application's own link from the token with `href`, so it
lands on a page of the application. A failure Better Auth answers with a
redirect, such as a used magic link's `?error=INVALID_TOKEN`, fails as a
rejection does, with `error.code` naming it; any other redirect Better Auth
answers reaches the action as `AuthRedirect`, which the error page follows.
Better Auth keeps its own time: its token and session expiry follow the wall
clock, not `testClock`, so a test of them starts the test clock at the
present and the application's own rules read Effect's `Clock`. `signedIn`
signs a request in without a Better Auth session, so a Better Auth endpoint
that needs one, such as deleting the account, is tested after a real sign-in
through `testBrowser`.

An application that loads Better Auth on first use, to keep it out of a
Worker's startup, gives `auth.client` a wrapper whose endpoints load it, and
`betterAuthLogoutAction` works through it. `betterAuthRedirect` and
`betterAuthCall` find the endpoint's path on Better Auth's instance, so
through a wrapper they fail and say why: send those forms to Better Auth's
handler yourself, by path, or give `auth.client` the instance. Importing
anything from `better-auth` into a module the Worker loads at startup,
`APIError` included, loads Better Auth with it.

A signed-out visitor to a guarded page is redirected with 302 on a page load
and 303 on an Inertia visit, as Inertia requires; a test asserts the
`Location`, `/login?redirect=...`, rather than the status. A form posted
while signed out, as after a session expires, cannot be replayed, so
`?redirect=` names the page the form was on, and a JSON client gets a 401.

`betterAuthHandler()` forwards a request to Better Auth's own API. Register
it on the paths the application needs Better Auth to answer itself, and no
others: an OAuth provider's callback,
`routes.get(paths.authCallback, betterAuthHandler())` with
`authCallback: '/api/auth/callback/{provider}'`, as
[Signing in with an OAuth provider](auth-plugins.md#signing-in-with-an-oauth-provider) shows.
Browser code that calls Better Auth directly (its client SDK) needs all of it,
`routes.all(paths.authApi, betterAuthHandler())` with
`authApi: '/api/auth/*'`, which exposes every endpoint Better Auth and its
plugins define past the application's guards: the organization plugin's
role changes and deletions, and sign-up, update-user and the email-OTP
sign-in and phone-number verify that make a user on first use, which write
the user fields declared `input: true`, and plugins' user fields such as the
phone-number plugin's `phoneNumber` and the username plugin's `username`,
without the application's actions checking them. Once the registered Better Auth declares such a field, TypeScript asks
for the ones visitors may set there, `betterAuthHandler({ settable: ['timeZone'] })`,
and the handler refuses a request setting any other with a 400; `settable: []`
keeps every field to the application's own forms. It reads a body within
setupWeb's `bodyLimit`, as `validateRequest` does, and answers a larger one
with a 413 before Better Auth reads it. A sign-in or a call that writes user
fields is read as Better Auth will read it, so its body is JSON, typed
`application/json` or `application/*+json`, or a form; any other is refused
with a 415.

## The sign-in page

```tsx
// src/pages/Auth/Login.tsx
import { useForm } from '@inertiajs/react'
import type { FormEvent } from 'react'
import type { FormInput, WebPage } from '@popcomputer/web/react'
import type { SignIn } from '../../forms'
import { paths } from '../../paths'

const Login: WebPage<'Auth/Login'> = () => {
  const form = useForm<FormInput<typeof SignIn>>({ email: '', password: '' })

  const submit = (event: FormEvent) => {
    event.preventDefault()
    form.post(paths.login, { onFinish: () => form.reset('password') })
  }

  return (
    <form onSubmit={submit}>
      <label>
        Email
        <input type="email" value={form.data.email} onChange={(event) => form.setData('email', event.target.value)} />
      </label>
      {form.errors.email && <p role="alert">{form.errors.email}</p>}

      <label>
        Password
        <input type="password" value={form.data.password} onChange={(event) => form.setData('password', event.target.value)} />
      </label>

      <button type="submit" disabled={form.processing}>Sign in</button>
    </form>
  )
}

export default Login
```

## The page that proves an address

The link a sign-up emails opens this page ([Proving an address](auth.md#proving-an-address)).
Only its button proves the address, so a mail scanner's fetch proves nothing:

```tsx
// src/pages/Auth/VerifyEmail.tsx
import { useForm } from '@inertiajs/react'
import type { WebPage } from '@popcomputer/web/react'
import { paths } from '../../paths'

const VerifyEmail: WebPage<'Auth/VerifyEmail'> = ({ token }) => {
  const form = useForm({ token })

  return (
    <form onSubmit={(event) => { event.preventDefault(); form.post(paths.verifyEmail) }}>
      <button type="submit" disabled={form.processing}>Confirm my email address</button>
    </form>
  )
}

export default VerifyEmail
```

---

<!-- docs/state-machines.md -->

# State machines

Some of what the framework keeps changes over a sequence of requests: a
count, a cookie, a cached value, a one-time token. Each is a state machine,
whether or not its code says so, and each promises something that concurrent
requests, other tabs, prefetches, retries and expiry can break. This page
lists them, says what each promises, and points to the TLA+ models in
[`state-machines/`](state-machines/) that check the promises over every
order of steps within small bounds. The models are checked with TLC through
pstack's `/statechart` skill, which also draws the charts here; the
project's own verify skill, `.claude/skills/verify-state-machines`, says how
to check a change against them.

## The lifecycles

| Lifecycle | Where | States | What moves it |
|---|---|---|---|
| An account's sign-ins | `src/effect/sign-in-limits.ts` `withinSignInLimits`, `sweepSignInFailures` | spent, counting, cooling, cooled: conditions on its `rateLimit` row | a password sign-in, its answer, time, the sweep |
| Inertia's history | `src/middleware.ts` `web()`, `src/page-version.ts` | per tab: its key, its entries, its page's version; per browser: the session cookie and the clear | a page, an answer that ends or starts a session, Back |
| Flash and a failed form's errors | `src/flash.ts` `openFlash` | the cookie's errors, flash values and clear; per request, delivered or not | a redirect, a page, a JSON answer, a prefetch |
| Purges a route owes | `src/effect/response-cache.ts` `makePendingPurges`, `makePendingCacheTags` | open with tags, then taken; a later add is a defect | `purgeCache`, `tagCache`, the route's success |
| `routes.run`, `routes.queue`, `routes.scheduled` | `src/effect/routing.ts` `runJobs`, `failRun`, `run` | registered, done, resolved or rejected; a message acked or retried | the job's exit, its purge |
| Background work of a request | `src/effect/bridge.ts` `createExecutionContextSupervisor` | idle, pending, draining, drained, disposed | `background()`, `waitUntil`, the runtimes' disposal |
| The default page cache | `src/page-cache.ts` | per request: dynamic or not; per URL: stored with a deploy's id | a read of a header, binding or the database; the response |
| The data cache | `src/cache.ts` `cache`, `cacheGet`, `cacheSet`, `invalidateCacheTags` | an entry fresh, stale or expired; a tag's generation | a read, a store, a purge |
| The session lookup | `src/effect/auth.ts` `loadUserMiddleware` | the request's user, set once before the action; renewal cookies | the lookup, a renewal, a revocation |
| An address and its links | `docs/auth.md`, `docs/auth-plugins.md`, `tests/better-auth/app.ts` | none, registered, proven; a link's token unused or used | sign-up, the link's page and button, sign-in, change-email |
| Application cookies | `src/effect/cookies.ts` | the browser's value; a signed one's signature | `set`, `clear`, the next request |
| Guards and bound records | `src/effect/routing.ts`, `src/effect/guard.ts` | per guarded binding: undecided, read, decided | a guard's read, its layer built, `bound()` |

## The models

Each model holds the code as it is, `Design = "code"`, and the code of
release 1.6.0, `Design = "1.6"`, on which every rule breaks: a rule never
seen to fail proves nothing. Each `.cfg` beside a model sets its bounds.

### An account's sign-ins

[`SignInLimits.tla`](state-machines/SignInLimits.tla): three guessers and
the owner, `max` 2, a cooldown of one tick and a window of four.

- **AtMostMaxGuessesAtOnce**: however many guesses arrive together, at most
  `max` reach the password check, unless the owner signs in between them.
- **NoFreshBudgetAfterCooldown**: once the account has cooled down, its count
  starts again from 1 only after a whole window with no guess, counted from
  the end of the cooldown.
- **OwnerSignInClearsCount**: after the owner signs in, only failures after
  that count.

All three hold on the code over 23,529 states. On 1.6, which read the count
before Better Auth's call and wrote it after, three guesses sent together
all reached the check; a guess that failed while the owner's password was
checked stayed counted; and a count past `max` started again a window after
its last failure, its cooldown spent toward the window. The code counts
each sign-in in one conditional upsert before the call, and its row lasts a
window past the end of its cooldown. In the whole graph of a smaller model,
a sign-in during a cooldown is refused and stays there:

```mermaid
stateDiagram-v2
  s0: No sign-ins counted
  s1: Counting sign-ins, a password being checked
  s2: Cooling down, a password being checked
  s3: Counting sign-ins
  s4: Cooldown over, count kept, a password being checked
  s5: No sign-ins counted, a password being checked
  s6: Cooling down
  s7: Cooldown over, count kept
  [*] --> s0
  s0 --> s1: a guess is counted or the owner sends the password
  s1 --> s2: the owner sends the password or a guess is counted
  s1 --> s3: a guess fails
  s1 --> s0: the owner signs in
  s2 --> s4: time passes
  s2 --> s5: the owner signs in
  s3 --> s2: the owner sends the password or a guess is counted
  s2 --> s0: the owner signs in
  s4 --> s5: the owner signs in
  s4 --> s2: a guess is counted or the owner sends the password
  s5 --> s1: a guess is counted
  s5 --> s0: a guess fails
  s2 --> s6: a guess fails
  s4 --> s0: the owner signs in
  s6 --> s7: time passes
  s4 --> s7: a guess fails
  s7 --> s2: a guess is counted or the owner sends the password
```

The model leaves out the Rate Limiting binding, which only narrows a burst
at each Cloudflare location, and the password hash's cost.

### Inertia's history

[`HistoryClear.tla`](state-machines/HistoryClear.tla): two tabs, Ada and
Grace, eight steps, with `history.encrypt`'s default and with `true`.

- **BackShowsNoOneElsesPage**: Back never shows a member's page from history
  in a tab whose page is now someone else's, or a guest's, without asking the
  server.

It holds on the code in both modes, over 36,831 and 37,951 states. On 1.6,
the one-time clear reached only the tab that showed the first page after a
switch: Ada signs in, tab 1 shows her page, Grace signs in, tab 2 shows a
page and takes the clear, tab 1 shows Grace's page, and Back in tab 1 shows
Ada's. Under `encrypt: true`, a cookie that simply expired cleared nothing.
The code gives a signed-in page a version that names its user, and Inertia
asks the server for an entry whose version is not the current page's.

The model leaves out Inertia's prefetch cache. Back pressed in a tab before
it asks for any page after the session ended elsewhere is still answered
from that tab's history: only the server knows the session ended.

### The data cache

[`DataCache.tla`](state-machines/DataCache.tla): one value under one tag,
and `cacheSet` given the Effect that reads the record, or, as
`CacheSetGiven = "value"`, a value an action read in an earlier step.

- **NoReadAfterPurgeReturnsTheOldValue**: once a write's purge has run, no
  read returns the value from before it, but one `cacheSet` was given after
  the purge.
- **CacheSetStoresOnlyCurrentValues**: `cacheSet` stores no value a purge has
  already replaced where a read would find it. Given its read, `cacheSet`
  reads the generations first, as `cache` does, so a value the read returned
  before a purge is stored under the older generation and never read. Given
  a value, it stores against the generations as they are when it runs, and
  the rule breaks: a known limit of that form.

Given its read, both hold on the code over 405 states
(`DataCache.code.cfg`); given a value, the first holds over 417 and the
second breaks in three steps (`DataCache.code.value.cfg`), as
`tests/cache.test.ts` and `tests/fuzz/data-cache.test.ts` also find. On
1.6, `cacheSet` stored no tag and `cacheGet` read none: a value stored by
`cache` or `cacheSet`, its record written and purged, came back from
`cacheGet`. `cache` reads the generations
before it computes, so a purge during its computation leaves the value a
miss. The model leaves out time, so `ttl`, and KV's eventual consistency,
which [the data cache](data-cache.md) describes.

### A magic link

[`MagicLink.tla`](state-machines/MagicLink.tla): the member's link, and a
mail scanner that fetches it and presses no button.

- **OnlyTheMemberSignsIn**: no one but the member signs in with their link.
- **TheMemberSignsIn**: the member who follows an unexpired link is signed in.

Both hold on the code, whose link opens a page whose button posts the token.
On 1.6's template, the scanner's fetch signed it in and left the member's
click on an expired link.

### A failed form's errors

[`Flash.tla`](state-machines/Flash.tla): a form that fails, and another
request from the same browser, a poll or another tab, that renders a page.

- **TheFormShowsItsErrors** breaks, and stays a known limit: the flash
  cookie is one value per browser, so a page the other request renders after
  the form's answer takes the errors, and the form's own page shows none.
  Inertia follows the form's redirect at once, so only a request in flight
  then can take them.

## Known limits

The models found these, or the inventory did, and the framework keeps them:

- A failed form's errors, and flash values, go to the next page the browser
  renders, in whichever tab; a JSON answer drops them.
- A job whose purge fails after its writes committed is retried whole, as
  [background work](background.md) says, so a job must be safe to run twice;
  a queue message is acked before the `background()` work it started settles.
- A value given to `cacheSet` that was read before a write whose purge ran
  before `cacheSet` is stored as current, until its `ttl`. Given the Effect
  that reads it instead, `cacheSet` keeps no value a purge during the read
  made stale.
- A GET that read a record before a write and stores its response after the
  write's purge keeps the old page in Workers Cache until its `maxAge`.
  `cache` refuses such an entry by its tags' generations; Workers Cache
  answers before the Worker runs.
- A promise a request service hands to `waitUntil` as its scope closes,
  after the request's background work has drained, is kept alive, but its
  failure is reported nowhere: the runtime whose observer would report it is
  gone by then.
- A signed application cookie's signature covers its name and value, not its
  expiry, so a copied value stays valid after its `Max-Age`.

---

<!-- docs/test-database.md -->

# A database for tests

Test against the database family production uses, so transactions, batches
and constraint errors behave the same:

- **Postgres** (including through Hyperdrive): an in-process
  [PGlite](https://pglite.dev) database with `drizzle-orm/pglite`. Apply the
  migrations drizzle-kit generates with `applyMigrations('./drizzle', (sql) =>
  client.exec(sql))`, and pass the Drizzle client as `testEnv`'s `database`. It
  replaces setupWeb's `database` factory for that request, so the database
  operations, route model binding and Better Auth all use it. PGlite runs one
  transaction at a time, so a test of concurrent requests passes even when
  the code races; test locking against a real Postgres, passing a postgres.js
  Drizzle client as `database` the same way, in a test that runs when a
  database URL is set.
- **Cloudflare D1**: Miniflare's real D1 runs under Bun, in process.
  `testD1({ migrations })` from `@popcomputer/web/testing` hands
  out D1 databases, each newly created, migrated with drizzle-kit's
  migrations in one batch, and empty. Point it at the folder wrangler applies
  migrations from, `wrangler.jsonc`'s `migrations_dir` (`migrations` unless it
  says otherwise), with drizzle-kit's `out` set to the same folder. The
  databases are typed as the application's D1 binding:
  `testEnv({ ...testBindings, DB: await databases.fresh() })`. Starting
  Miniflare takes a moment, so one holds many databases and another starts
  when they run out. Stop them once, after every test file, with
  `afterAll(() => databases.dispose())` in a file `bunfig.toml`'s
  `[test] preload` names: a Miniflare left running keeps its `workerd`
  process alive after `bun test` exits, and Bun shares modules between test
  files, so an `afterAll` in the module that creates the databases stops them
  while other files still use them. Miniflare's `getKVNamespace` and
  `getR2Bucket` give the other bindings; their types differ slightly from
  `@cloudflare/workers-types`', so provide a KV store to the data cache as
  `kvCache(kv)` in the test layer rather than as a binding, and type a binding
  an application service reads by the methods it calls (`KVNamespaceLike`
  from `@popcomputer/web/cache`, or a small interface of the R2 methods), so
  both objects fit.

```ts
// src/test-d1.ts
import { join } from 'node:path'
import { testD1 } from '@popcomputer/web/testing'

// Each test that asks gets a D1 database of its own.
export const databases = testD1({ migrations: join(import.meta.dir, '../migrations') })
```

`bun:sqlite` is a synchronous driver: it can stand in for neither, since
`dbTransaction` and `dbBatch` are type errors for it.

An application on D1 adds Cloudflare's types to `tsconfig.json`'s
`compilerOptions.types` (`"@cloudflare/workers-types"`, or the file
`wrangler types` writes), or imports a type from them, such as
`import type { D1Database } from '@cloudflare/workers-types'` in `src/env.ts`. Drizzle's D1 results name them, and without them a
result is `any`, which the database operations report as a type error.

```ts
// src/test-db.ts
import { PGlite } from '@electric-sql/pglite'
import { drizzle } from 'drizzle-orm/pglite'
import { applyMigrations } from '@popcomputer/web/testing'
import type { Database } from './db'
import * as schema from './schema'

const client = new PGlite()
await applyMigrations('./drizzle', (sql) => client.exec(sql))

export const testDb: Database = drizzle(client, { schema })
```

```ts
const env = testEnv(signedIn({ id: 'user-1' }), testBindings, { database: testDb })
```

One database shared by every test means each test seeds rows the others can
see. For a fresh database per test, migrate once and start each test from a
copy: PGlite saves a database's files with `dumpDataDir` and opens a copy with
`loadDataDir`, which takes a fraction of the time migrating a new one does.

```ts
// src/test-databases.ts
import { PGlite } from '@electric-sql/pglite'
import { drizzle } from 'drizzle-orm/pglite'
import { applyMigrations } from '@popcomputer/web/testing'
import * as schema from './schema'

const migrated = new PGlite()
await applyMigrations('./drizzle', (sql) => migrated.exec(sql))
const snapshot = await migrated.dumpDataDir('none')

// A database of its own for one test, migrated, and how to close it.
export function freshDatabase() {
  const client = new PGlite({ loadDataDir: snapshot })

  return { db: drizzle(client, { schema }), close: () => client.close() }
}
```

A test opens one in `beforeEach`, passes `db` as `testEnv`'s `database`, and
calls `close()` in `afterEach`.

A test whose visitors sign in through the application, as a `testBrowser`
does, needs no layer: `testEnv(testBindings, { database: testDb })`.

A request built with `testEnv` renders failures with their development
details unless its bindings set `ENVIRONMENT`; pass `ENVIRONMENT: 'production'`
to test the production error page. The `app` layer of `web.services` is
built once per test process, from the first request's bindings: replace an application service in
a test with a layer in `testEnv` rather than different bindings. A failed
build is retried by the next request.

---

<!-- docs/testing.md -->

# Testing

## A request through the application

Test routes through the application itself. `app.request` runs the real
middleware, route and action; `testEnv(layer, bindings)` builds the request
env. Services in the layer replace the ones the application gives, whether
in `web.services(...)` or on a route with `routes.provide()`, so a test fakes
a service that reaches another system wherever the application provides it.
The layer is built once a request, so a fake that keeps state keeps one.

`signedIn(user)` signs the request in without a session cookie. A user given
only an `id` is named `Test User`; when the user table has columns of its
own, the whole row is required, so pass the seeded row. Its session id is
`test-session`; pass `{ user, session }` for another.

```ts
// src/routes.test.ts
import { describe, expect, test } from 'bun:test'
import { readPage, signedIn, testEnv } from '@popcomputer/web/testing'
import app from './app'
import './routes'
import { testBindings } from './test-bindings'

describe('GET /projects/{project}', () => {
  test('shows a project to its owner', async () => {
    const res = await app.request(
      '/projects/project-1',
      { headers: { 'X-Inertia': 'true' } },
      testEnv(signedIn({ id: 'user-1' }), testBindings)
    )

    const page = await readPage(res, 'Projects/Show')

    expect(page.props.project.id).toBe('project-1')
  })

  test("answers 404 for another member's project", async () => {
    const res = await app.request(
      '/projects/project-1',
      {},
      testEnv(signedIn({ id: 'user-2' }), testBindings)
    )

    expect(res.status).toBe(404)
  })
})
```

`testBindings` is the application's test configuration: here, the URL of a
migrated test database with `project-1` owned by `user-1`, an auth secret, a
KV namespace and `testRateLimiter()` as the sign-in limiter. It holds every
var and secret `src/env.ts` requires, since `setupWeb` checks them as it does
in production. An `X-Inertia` request returns the page object as JSON, so tests
assert on the component and props rather than HTML.

An action is an Effect, so a test can also run it directly and provide the
services it reads, for example `Effect.provide(signedIn({ id: 'user-1' }))`.

## Reading a response

`readPage` reads a page response typed by the page registry, and rejects with
what the response was instead when it is not that page:

```ts
import { readPage, signedIn, testEnv } from '@popcomputer/web/testing'

const res = await app.request(
  '/projects/project-1',
  { headers: { 'X-Inertia': 'true' } },
  testEnv(signedIn({ id: 'user-1' }), testBindings)
)
const page = await readPage(res, 'Projects/Show')

page.props.project.createdAt // a string: the JSON the browser receives
```

The other readers work the same way, each typed and each saying what the
response was when it is not what the test expected: `readJson(res, Schema)`
for a JSON response, where `await res.json()` is `unknown` and checks
nothing, `readError(res)` for a failure's envelope (and
`readError(res, Schema)` for a body declared by a schema), `readErrorPage(res)`
for the error page a visit rendered, and `readCookie(res, cookie)` for the
value a response set for a declared cookie.

## One visitor across requests

A test that makes several requests as one visitor, such as adding to a cart
and then checking out, uses `testBrowser(app, env)`. It keeps the cookies
responses set, sends them to the paths they cover, names the page it last
showed as the `Referer` of a form it posts and that page's origin as its
`Origin`, as a browser does for any request but a `GET` or `HEAD`, and follows
redirects with `browser.follow(res)`; `browser.setCookie(name, value, path)`
gives it a cookie.

A form's next page receives its `flash` values and field errors through a
cookie the redirect sets. `testBrowser(app, env).follow(res)` requests the
redirect's `Location` as the browser would, with that cookie, whether the
browser sent the form or the test posted it with `app.request`. Post with a
`Referer`, as a browser does, so a failed form goes back to it:

```ts
import { readPage, signedIn, testBrowser, testEnv } from '@popcomputer/web/testing'

const env = testEnv(signedIn({ id: 'user-1' }), testBindings)
const failed = await app.request(
  '/projects',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Referer: 'http://localhost/projects' },
    body: JSON.stringify({ name: '' }),
  },
  env
)
const form = await readPage(await testBrowser(app, env).follow(failed), 'Projects/Index')

form.props.errors.name // 'This field is required'
```

## Fakes for other systems

Replace a service that reaches another system, such as a mailer or a payment
provider, with a fake that records what it was asked to do, and give it to
`testEnv` with the signed-in user. `Layer.succeed(Service, fake)` swaps any
service the application provides:

```ts
import { Context, Effect, Layer } from 'effect'
import { signedIn, testEnv } from '@popcomputer/web/testing'

class Mailer extends Context.Service<Mailer, {
  readonly send: (to: string, subject: string) => Effect.Effect<void>
}>()('app/Mailer') {}

const sent: Array<{ readonly to: string; readonly subject: string }> = []
const FakeMailer = Layer.succeed(Mailer, Mailer.of({
  send: (to, subject) => Effect.sync(() => { sent.push({ to, subject }) }),
}))

const env = testEnv(Layer.merge(signedIn({ id: 'user-1' }), FakeMailer), testBindings)
```

A test checks what a write purges by replacing `ResponseCacheService` with a
recorder:

```ts
import { Effect, Layer } from 'effect'
import { ResponseCacheService, type ResponseCachePurgeInput } from '@popcomputer/web/effect'
import { signedIn, testEnv } from '@popcomputer/web/testing'

const purged: ResponseCachePurgeInput[] = []
const RecordPurges = Layer.succeed(ResponseCacheService, {
  isAvailable: true,
  purge: (input) => Effect.sync(() => { purged.push(input) }),
})

const env = testEnv(Layer.merge(signedIn({ id: 'user-1' }), RecordPurges), testBindings)
```

The layers given to `web.services` are still built, so the test bindings
include the vars and secrets those layers read even when a fake replaces
them. Effect `Config` reads the request's bindings, so a test sets a var or
secret in `testEnv`'s bindings. The `app` layer is built once per test
process, from the first request's bindings: a test that needs another value
for an application service gives it a layer in `testEnv` instead.

## Time

Rules that depend on the time, such as an invitation that expires after seven
days, read it from Effect's `Clock` (`DateTime.now`, `Clock.currentTimeMillis`)
rather than `new Date()`. `testClock(start)` gives a test one clock that every
request it makes reads, and the test moves it between requests:

```ts
import { Layer } from 'effect'
import { signedIn, testClock, testEnv } from '@popcomputer/web/testing'

const time = await testClock(new Date('2026-03-01T09:00:00Z'))
const env = testEnv(Layer.merge(signedIn({ id: 'user-1' }), time.layer), testBindings)

await time.advance('8 days')
const expired = await app.request('/invites/abc', {}, env)

// A request that waits on the clock, such as a delivery retrying with
// Schedule.exponential: settle moves the clock until it answers.
const delivered = await time.settle(app.request('/webhooks/deliver', { method: 'POST' }, env))
```

## What test files share

Bun runs every test file in one module registry, so a clock or a test
database created at the top of a shared support module is shared by all the
files. A file that moves the clock sets it back in `beforeEach` (`await
time.set(start)`), and a file that writes rows seeds and reads its own. A job
that reads every tenant's rows, such as a monthly invoicing cron, sees other
files' seeds too, so seed through the application's own writes (or keep
counters and sequences consistent), and give such a test its own database.

[A database for tests](test-database.md) shows the database a test runs against,
and [Fuzzing](fuzzing.md) checks the application's routes on generated requests.

---

<!-- docs/validation.md -->

# Validating input

```ts
import { Effect } from 'effect'
import {
  action,
  authorize,
  dbMutation,
  redirect,
  validateRequest,
} from '@popcomputer/web/effect'
import { CreateProject } from '../forms'
import { paths } from '../paths'
import { projects } from '../schema'

export const createProject = action(
  Effect.gen(function* () {
    const auth = yield* authorize()
    const input = yield* validateRequest(CreateProject)

    const [project] = yield* dbMutation((db) =>
      db.insert(projects)
        .values({ ...input, id: crypto.randomUUID(), userId: auth.user.id })
        .returning()
    )

    return yield* redirect(paths.project, { project: project.id })
  })
)
```

`validateRequest` reads route params, query and body, and returns the decoded
input with every key the schema does not declare removed. A body sent as JSON
is read as JSON whatever its media type, as `fetch` sends a string as
`text/plain`, and a form post's fields are nested. A key that two
sources provide with different values fails validation, so a body field cannot
replace a route parameter; pass `request: { order: ['body'] }` to read only the
body.

Dates and times have strict validators: `isoDate` accepts a calendar day
written `YYYY-MM-DD` and keeps it as that string, since a day has no time
zone, and `isoDateTime` accepts a moment with its zone,
`2030-05-01T09:00:00Z`, as a `Date`. Each refuses a day the calendar lacks,
and `isoDateTime` a time without a zone, which `coercedDate` would read in the
server's zone. The form validators coerce, since a form sends every value as
a string: `coercedNumber` accepts `"12"`. A JSON endpoint's contract, whose
clients send JSON's own types, declares numbers with Effect's schemas,
`S.Int.check(S.isGreaterThan(0))`, so a string is refused and the published
description says what the endpoint accepts.

A multipart form's files reach the schema as `File` values. Check them with
`upload({ types: ['image/png', 'image/jpeg'], maxBytes: 5_000_000 })`, or
`nullableUpload(...)` when the file is optional; a file input left empty is
no file. [Serving an upload back](responses.md#serving-an-upload-back) shows
serving one back.

`validateRequest` reads at most 1 MiB of a body, or setupWeb's `bodyLimit`,
counting its declared `Content-Length` and the bytes as they arrive, and
refuses a larger one before parsing it: a JSON client gets a 413
(`WEB_VAL_007_BODY_TOO_LARGE`) and a page's form goes back with a `form`
error. An action whose form uploads files raises it past their `maxBytes`,
`validateRequest(ReceiptForm, { bodyLimit: 6_000_000 })`, as `ReceiptForm`
below needs. Headers and the
raw body, such as an `Idempotency-Key` or a webhook signature, are read from
`RequestService`'s `header()` and `raw()`.

## User input in

A filter form sent with GET carries every field, empty or not, so read each
filter with `nullable(...)` or `nullableString`, which read an empty or absent
field as `null`; `S.optional(coercedNumber)` rejects `?minAmount=`. Limits
take the message the form shows, through Effect's checks. An upload names the
types it accepts: a family such as `image/*` leaves out SVG, which a browser
runs script in, and the type is the one the browser declares for the file:

```ts
import { Schema as S } from 'effect'
import { coercedNumber, nullable, nullableString, requiredString, upload } from '@popcomputer/web/schema'

const ClaimFilters = S.Struct({
  stage: nullable(S.Literals(['approver', 'finance'])),
  minAmount: nullable(coercedNumber),
  search: nullableString,
})

const ReceiptForm = S.Struct({
  description: requiredString.check(S.isMaxLength(200, { message: 'Keep it under 200 characters.' })),
  receipt: upload({ types: ['image/png', 'image/jpeg', 'application/pdf'], maxBytes: 5_000_000 }),
})
```

Read a link with `url`, or `nullableUrl` when it is optional. Each accepts
only `http:` and `https:` links and refuses every other scheme with "Use a
link that starts with https:// or http://.": a page shows a stored link in an
`href`, where a `javascript:` or `data:` link runs script on the
application's origin. The scheme is read as a browser reads it, so
`JavaScript:` or spaces before it make no difference. Keep an email address
with `email` and build its `mailto:` link in the page.

A body field named like one of the route's placeholders, such as `claim` on
`PUT /claims/{claim}`, must carry the same value or the request fails
validation, whether or not the schema reads it; leave such fields out of the
form.

## Other patterns

- **Forms built per record**, such as a quiz's answers: build the schema from
  the record (`S.Struct({ answers: S.Tuple(questions.map(answerSchema)) })`)
  and annotate its type, since a tuple built from a runtime array infers as
  empty; errors arrive keyed by position, as `answers.3`. A schema built from
  the validators also serves as a page's props schema, so a filter form's
  query and the page that shows it share one.
- **Lists in forms**: decode a list with `S.Array(Item)`; a failing item's
  errors are keyed by its path, as `items.2.amount`. A failed validation lists
  at most 100 fields, then says on `form` that more were invalid. A request
  of more than 1000 values stops at its first invalid field and says so on
  `form`, since checking every one would hold an issue per item in memory;
  `parseOptions: { errors: 'all' }` asks for every one. Bound a
  list with `maxItems(Item, 50)`, which refuses a longer one with its own
  message before decoding any item. A JSON body, a form post
  and a multipart post (which Inertia sends for a form with a file) all
  decode the same: form fields named `items[2][amount]` or `items.2.amount`
  nest into the list, and every value of a `tags[]` field, in a form or a
  query string, is a list. A list's largest index may be at most 20 past the
  number of items sent, so renumber rows a form removes: `items[50][amount]`
  sent alone stays a key, and fails to decode as a list. Read them in React from
  the page's `errors` prop, ``errors[`items.${index}.amount`]``, which takes any
  path; Inertia's `useForm().errors` is keyed by the form's top-level fields
  only, so reading a nested path from it needs a cast. A wizard whose final
  submit carries every step's fields validates each step's part with
  `validateRequest(Step, { redirectTo: href(paths.applyStep, { step }) })`, so
  a failure goes back to that step with its errors.
- **Forms whose fields depend on earlier answers**, such as a survey's
  conditional questions: validate in two passes, `validateRequest(Envelope)`
  for what decides the rest, then `validateRequest(schemaFor(envelope))`; the
  body is read once and kept. Give an optional nested group `nullable(Group)`,
  which reads a group whose every field is blank as `null`, or
  `S.optionalKey(Group)`, not a decoding default: in effect 4.0.3 a struct
  with a decoding default reports its first missing field and drops its
  siblings' errors.

---

<!-- docs/webhooks.md -->

# Webhooks verify the raw body, then record the event once

A webhook's signature covers the exact bytes sent, so read the raw body with
`RequestService`'s `raw()` rather than `validateRequest` (read
`raw().clone().text()` when `validateRequest` reads the body afterwards),
verify it with Web Crypto (`crypto.subtle.verify` compares in constant time), and only then decode
it. Read the secret with `config.redacted`, which reads the Worker's binding
and keeps it out of logs. Providers retry, so record each event id under a
unique key and treat a duplicate as already handled. On D1, insert the event
id in the same `dbBatch` as the writes it causes, so a replay's unique
violation undoes the whole batch:

```ts
import { eq } from 'drizzle-orm'
import { DateTime, Redacted } from 'effect'
import { orders, webhookEvents } from '../schema'

const PaymentEvent = S.Struct({ id: S.String, orderId: S.String })

async function verifySignature(secret: string, body: string, signature: string) {
  // An HMAC-SHA256 in hex is 64 hex digits: anything else is not a signature.
  if (!/^[0-9a-f]{64}$/.test(signature)) return false

  const encoder = new TextEncoder()
  const key = await crypto.subtle.importKey(
    'raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']
  )
  const bytes = Uint8Array.from(signature.match(/../g) ?? [], (pair) => Number.parseInt(pair, 16))

  return crypto.subtle.verify('HMAC', key, bytes, encoder.encode(body))
}

export const paymentWebhook = action(Effect.gen(function* () {
  const request = yield* RequestService
  const secret = yield* config.redacted('PAYMENT_WEBHOOK_SECRET')
  const body = yield* Effect.promise(() => request.raw().text())
  const signature = request.header('X-Signature') ?? ''

  if (!(yield* Effect.promise(() => verifySignature(Redacted.value(secret), body, signature)))) {
    return yield* httpError(401, 'Invalid signature')
  }

  const event = yield* S.decodeUnknownEffect(S.fromJsonString(PaymentEvent))(body).pipe(
    Effect.catchTag('SchemaError', () => httpError(400, 'Malformed event'))
  )

  const paidAt = DateTime.toDateUtc(yield* DateTime.now)

  return yield* dbTransaction(Effect.gen(function* () {
    yield* dbMutation((db) => db.insert(webhookEvents).values(event))
    yield* dbMutation((db) => db.update(orders).set({ paidAt }).where(eq(orders.id, event.orderId)))
  })).pipe(
    Effect.andThen(noContent()),
    Effect.catchTag('DatabaseConstraintViolation', (violation) => Effect.gen(function* () {
      if (violation.constraint !== 'unique') return yield* violation

      // A replay of an event already recorded.
      return yield* noContent()
    }))
  )
}))
```

A refusal answers through `httpError`, so the provider gets the same JSON
envelope as every other client, and an acknowledgement needs no body: any
`2xx` tells the provider to stop retrying.